Référence du protocole HTTP qwen serve

Étape 1 de la conception du démon qwen-code . Toutes les routes se trouvent sous l’URL de base du démon (par défaut http://127.0.0.1:4170).

Cette référence décrit les routes HTTP et le cadrage SSE. Lisez-la conjointement avec le schéma d’événements typé pour les contrats de charge utile, les raisons de resynchronisation et les ancres d’historique, le guide du bus d’événements et de la relecture pour la livraison et la contre-pression, et les capacités et le versionnement pour le protocole v1 existant et les règles de compatibilité. L’index de la documentation du démon relie l’ensemble complet des contrats.

Authentification

Lorsque le démon a été démarré avec --token ou QWEN_SERVER_TOKEN — ou lié à une adresse non-loopback sans aucun des deux, ce qui génère un jeton bearer éphémère affiché une seule fois au démarrage — chaque route API normale sauf /health sur les liaisons loopback ordinaires doit comporter :

Authorization: Bearer <token>

En l’absence de jeton configuré sur le loopback par défaut, l’en-tête est optionnel et les requêtes arrivant via le listener principal disposent de la pleine autorité API opérateur. La confiance dans l’espace de travail, la propriété de session, X-Qwen-Client-Id, les permissions, les fonctionnalités, la validation et les vérifications de ressources s’appliquent toujours. La comparaison de jetons est à temps constant. Les réponses 401 sont uniformes entre missing header / wrong scheme / wrong token.

--open-with-auth. Ce mode CLI désactivé par défaut nécessite une liaison loopback et un Web Shell disponible. Il réutilise la sélection normale de --token sur QWEN_SERVER_TOKEN, ou génère 32 octets aléatoires encodés en base64url avant le démarrage du démon si cette sélection est vide. Le navigateur reçoit le jeton bearer sélectionné via #token= et le stocke par onglet ; le protocole et le middleware voient un jeton configuré ordinaire. La livraison de fragment repose sur le jeton résolu, pas sur ce drapeau : tout lancement --open attache le jeton bearer résolu — configuré ou généré — au fragment #token= de l’URL lancée (visible par les utilisateurs locaux via ps / /proc, comme l’avertit le lanceur), donc une liaison non-loopback avec --open seul transmet son jeton bearer généré au navigateur de la même manière ; les contributions distinctes de ce drapeau sont la génération de jeton sur loopback et le repli manuel d’URL pour les environnements sans navigateur. Seuls les appelants intégrés directs qui ignorent RunHandle.resolvedToken, et les clients qui ne lancent jamais de navigateur, ne reçoivent aucun identifiant automatique. Les environnements sans navigateur impriment l’URL de fragment contenant le secret pour une ouverture manuelle. /health loopback et les actifs statiques du Web Shell conservent les exemptions décrites ci-dessous ; --require-auth continue de contrôler l’accès à /health.

L’ingress webhook de canal (POST /channels/:channelName/webhooks/:source) est séparé de ce contrat bearer dans tous les modes. Lorsqu’il est monté, il est enregistré avant bearerAuth et s’authentifie avec son x-qwen-webhook-secret configuré ; la rotation du jeton bearer du démon ne fait pas tourner les secrets des sources de webhook.

Exemption /health (Bctum) : sur les liaisons loopback (127.0.0.0/8 / localhost / ::1 / [::1]), /health est enregistré AVANT le middleware bearer, afin que les sondes de vivacité à l’intérieur du pod n’aient pas besoin de porter le jeton même lorsque le démon a été démarré avec --token. Les liaisons non-loopback (--hostname 0.0.0.0 etc.) contrôlent l’accès à /health avec les autres routes API normales — voir la section GET /health pour la justification.

--require-auth (#4175 PR 15). Passez ce drapeau au démarrage pour étendre la règle « doit avoir un jeton » au loopback également. Le démarrage échoue lorsqu’aucune source de jeton ne se résout — sur loopback cela signifie --token, QWEN_SERVER_TOKEN ou --open-with-auth (qui installe son propre jeton généré avant le démarrage, donc --require-auth --open-with-auth démarre). L’échec rapide est spécifique au loopback : une liaison non-loopback résout le jeton bearer éphémère qu’elle génère lorsque aucune des sources configurées n’est présente, et cela satisfait au drapeau. L’exemption /health est supprimée dans les deux cas, donc /health exige également Authorization: Bearer ….

Lorsque le drapeau est activé, le middleware global bearerAuth contrôle l’accès à chaque route API normale — y compris /health et /capabilities. L’ingress webhook de canal reste authentifié indépendamment par secret partagé, et les routes document et actifs du Web Shell restent pré-authentifiées. Un client non authentifié ne peut donc pas pré-voler caps.features pour découvrir que l’authentification est requise : la surface de découverte pour ce cas est le corps de réponse 401 lui-même (uniforme entre les routes contrôlées par bearer selon la section Authentication). La balise de capacité require_auth est une confirmation post-authentification — une fois qu’un client s’authentifie avec succès et lit /capabilities, la présence de la balise confirme que le démon a été démarré avec --require-auth (utile pour les interfaces d’audit/conformité et pour que les clients SDK affichent « ce déploiement est durci » dans un panneau de paramètres). Les routes de mutation strictes acceptent les requêtes du listener principal loopback de confiance, les requêtes authentifiées par bearer, ou les requêtes Local Control appariées. Les embeds token-less non fiables reçoivent toujours 401 { code: "token_required", error: "…" } ; avec --require-auth, le middleware bearer global rejette d’abord avec le corps legacy Unauthorized.

--allow-origin <pattern> (T2.4 #4514 ). Les clients navigateur touchant le démon en cross-origin sont bloqués par défaut — une requête portant un en-tête Origin retourne 403 {"error":"Request denied by CORS policy"} car les clients CLI/SDK n’envoient jamais Origin et le démon traite sa présence comme un signe que la requête provient d’un contexte navigateur que l’opérateur n’a pas activé. Une exception précède le mur sur une liaison non-loopback avec jeton : une requête same-origin (Origin égal au schéma du socket direct plus l’autorité normalisée Host) est authentifiée par bearer et son Origin est retiré sur le listener principal — avec un bearer valide, le statut de la route suit, avec un bearer manquant ou invalide un 401, sauf les routes pré-authentifiées document Web Shell, /assets/*, /manifest.webmanifest, /sw.js et /mcp-app-sandbox, qui sont servies sans identifiant comme dans tous les autres modes — et seules les valeurs Origin cross-origin ou non correspondantes conservent l’enveloppe 403. Passez --allow-origin <pattern> (répétable) au démarrage pour installer une liste blanche au lieu du mur. Chaque motif est soit :

• La valeur littérale * — admet toute origine. Risqué : le démarrage refuse si * est configuré mais qu’aucun jeton bearer ne se résout. Le garde lit le jeton résolu — --token, QWEN_SERVER_TOKEN, le jeton loopback généré par --open-with-auth, ou le jeton bearer éphémère généré par une liaison non-loopback lorsqu’aucune source configurée n’est présente — ce refus concerne donc uniquement le loopback. Le fil de trace au démarrage émet un avertissement stderr lorsque * figure dans la liste. Recommandation : associez-le à --require-auth sur les liaisons loopback afin que /health soit également protégé par le bearer — il est enregistré avant le middleware bearer sur loopback par défaut (afin que les sondes k8s/Compose puissent y accéder sans jeton), et une liste blanche * le rend accessible depuis tout navigateur cross-origin. --require-auth laisse toujours les ressources statiques Web Shell (/, /assets/*, /manifest.webmanifest, /sw.js, ainsi que les navigations documentaires /session/:id, /plugins, /channels, /live, /scheduled-tasks, /goals et /settings) pré-authentifiées sur loopback par conception — elles sont montées avant le middleware bearer — donc sous une liste blanche *, elles restent lisibles depuis tout navigateur cross-origin ; --no-web supprime cette surface. Sur les liaisons non-loopback, le bearer est déjà obligatoire au démarrage et /health est enregistré derrière lui. Les routes API normales sont protégées par bearer, l’ingress des webhooks de canal conserve sa propre protection par secret partagé, et les ressources statiques Web Shell (/, /assets/*, /manifest.webmanifest, /sw.js, ainsi que les navigations documentaires /session/:id, /plugins, /channels, /live, /scheduled-tasks, /goals et /settings) restent pré-authentifiées sauf si --no-web les supprime.
• Une origine d’URL canonique — <scheme>://<host>[:<port>]. Sans barre oblique finale, sans chemin, sans userinfo, sans requête. Le démarrage refuse avec InvalidAllowOriginPatternError si l’entrée échoue à la vérification aller-retour new URL(pattern).origin === pattern ; le message d’erreur nomme le motif incorrect et la forme canonique. Strict par intention : une normalisation silencieuse (par ex. la suppression d’une barre oblique finale /) laisserait passer les fautes de frappe et accepterait des entrées ambiguës. Sans jeton résolu — ce qui signifie après génération une liaison loopback — les entrées HTTP(S) sont limitées aux hôtes loopback ; une origine de navigateur non-loopback nécessite un jeton car elle peut sinon piloter l’API opérateur complète, y compris l’exécution de code en tant qu’utilisateur du démon. Les origines explicites d’extensions de navigateur conservent leur chemin existant d’automatisation locale sans jeton. Le journal de démarrage indique l’autorité accordée à toute origine de navigateur autorisée sans jeton.

Les origines correspondantes reçoivent les en-têtes de réponse CORS standard sur chaque requête :

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 renvoie l’origine de la requête verbatim (minuscules / majuscules telles que envoyées par le navigateur) plutôt que la valeur littérale *, même sous le motif * — les caches des navigateurs indexent les réponses dessus associé à Vary: Origin, et le renvoi laisse la possibilité d’ajouter Access-Control-Allow-Credentials dans une version ultérieure sans modification de schéma. Les en-têtes exposés permettent aux clients navigateur de respecter les indications de nouvelle tentative, de conserver l’époque SSE et de corréler les flux physiques acceptés. Access-Control-Allow-Credentials n’est PAS envoyé aujourd’hui : les identifiants de démon configurés utilisent bearer-in-Authorization, qui fonctionne en cross-origin sans credentials: 'include' ; l’autorité loopback de confiance n’a besoin d’aucun identifiant navigateur.

Les requêtes de pré-vol OPTIONS (OPTIONS avec Access-Control-Request-Method ou Access-Control-Request-Headers) court-circuitent avec 204 No Content plus les en-têtes ci-dessus. C’est le modèle CORS conventionnel et c’est sûr — la pré-vol confirme uniquement quelles méthodes/en-têtes le démon acceptera ; la requête subséquente réelle exécute toujours la porte Host puis soit l’autorité bearer/listener, soit la porte de secret partagé du webhook de canal avant toute lecture ou mutation d’état. Les requêtes OPTIONS simples provenant d’origines correspondantes continuent de s’écouler vers l’aval avec les en-têtes CORS attachés.

Les origines qui ne correspondent pas à la liste blanche reçoivent toujours 403 {"error":"Request denied by CORS policy"} — même enveloppe que le mur par défaut, afin que les clients ayant déjà analysé la réponse du mur n’aient pas à traiter spécifiquement les démons déployés avec liste blanche. Le chemin de rejet n’émet aucun en-tête Access-Control-* (le navigateur les ignorerait, et leur émission annoncerait indirectement la taille de la liste blanche via la présence d’en-têtes).

La liste de motifs configurée n’est volontairement PAS renvoyée dans /capabilities — un client navigateur connaît déjà sa propre origine (il a appelé le démon, après tout), et afficher la liste permettrait à un lecteur non authentifié de /capabilities d’énumérer toutes les origines de confiance (reconnaissance utile pour un déploiement mal configuré). Les clients SDK se basent sur la balise caps.features.allow_origin pour « ce démon honore les hits de navigateur cross-origin » sans avoir besoin de connaître les origines spécifiques.

Les requêtes en boucle locale (par exemple, le Web Shell appelant le démon sur la même 127.0.0.1:port) sont gérées par un shim de suppression d’origine séparé qui s’exécute AVANT l’intergiciel CORS et supprime l’en-tête Origin pour 127.0.0.1:port / localhost:port / [::1]:port / host.docker.internal:port ou l’adresse et le port de bouclage liés exacts. Il accepte également les formes sans port correspondant au schéma que les navigateurs envoient pour les ports par défaut : http://host sur le port 80 et https://host sur le port 443. Ces requêtes passent indépendamment de la configuration --allow-origin — les opérateurs n’ont pas besoin de lister le propre port du démon pour faire fonctionner le Web Shell.

Forme d’erreur courante

Les réponses 5xx portent le code et le data de l’erreur originale lorsqu’ils sont présents (style JSON-RPC — le SDK ACP transmet {code, message, data} depuis l’agent) :

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

Un JSON malformé dans un corps de requête renvoie :

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

avec le statut 400.

SessionNotFoundError pour un id de session inconnu renvoie :

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

avec le statut 404. Une fermeture concurrente utilise code: "session_closing".

WorkspaceMismatchError pour un POST /session dont le cwd ne se canonise pas vers un espace de travail enregistré renvoie 400 avec :

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

Utilisez ceci pour détecter les incompatibilités avant vol : lisez workspaceCwd depuis /capabilities et omettez cwd de POST /session (il retombe sur l’espace de travail principal), ou lorsque multi_workspace_sessions est annoncé, choisissez-en un parmi workspaces[].cwd.

POST /session dépassant le plafond --max-sessions configuré du démon renvoie 503 avec un en-tête Retry-After: 5 et :

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

Lorsque le plafond total effectif à l’échelle du démon rejette une nouvelle session — --max-total-sessions, ou le défaut décrit sous limits.maxTotalSessions — la même forme de réponse est renvoyée avec "scope": "total".

Les attaches aux sessions existantes NE SONT PAS comptées dans le plafond, de sorte que les reconnexions d’un démon inactif continuent de fonctionner même lorsqu’il est à pleine capacité.

Si le budget d’initialisation du canal ACP expire avant que newSession soit expédié, POST /session renvoie 504 avec Retry-After: 5 et :

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

timeoutMs — et le suffixe numérique de error — reflètent le budget --initialize-timeout-ms configuré du démon (les valeurs ci-dessus sont les défauts). La forme complète de nouvelle tentative sûre ci-dessus est émise uniquement pour la création simple de session, où l’initialisation du canal précède strictement toute mutation durable : sur ce chemin, le champ sideEffectPossible: false est faisant foi car l’initialisation précède la requête ACP newSession, et un client qui comprend ce contrat structuré peut retenter après le délai annoncé sans risquer un Session dupliqué.

Les requêtes portant branch ou worktree, ainsi que les délais d’initialisation signalés par les routes comportant des mutations autres que la création simple (par exemple POST /session/:id/branch et POST /session/:id/side-task, où un fork engagé peut survivre à l’échec de la poignée de main), renvoient le même 504 avec code: "init_timeout", phase et timeoutMs — mais SANS Retry-After, retryable ou sideEffectPossible. Pour celles-ci, le résultat de la mutation est inconnu : la préparation de la branche et du worktree modifie git avant l’initialisation du canal, et la tentative de rollback en cas d’échec est au mieux (un échec du rollback de checkout laisse l’espace de travail sur la nouvelle branche, et une nouvelle tentative peut révéler un conflit de branche existante). Les clients qui classifient toutes les réponses de mutation 5xx comme ambiguës restent conservateurs et en mode fail-closed, et doivent appliquer la même politique à la forme réduite. POST /session/:id/load et POST /session/:id/resume affichent la même init_timeout 504 réduite lorsque l’initialisation du canal dépasse le délai avant que la demande de restauration ne soit envoyée (l’étape ensureChannel) ; contrairement aux session_restore_timeout 504 documentés dans leurs listes d’erreurs, cette forme ne comporte ni Retry-After, ni retryable, et n’installe pas de verrou car la restauration n’a jamais été envoyée. Le délai d’envoi newSession sur POST /session est une exception : il renvoie 504 avec code: "init_timeout", retryable: true et un Retry-After dérivé du budget, mais sans phase ni sideEffectPossible, car le résultat de la création est ambigu. Toutes les autres étiquettes de délai conservent le mappage générique.

RestoreInProgressError — émis par POST /session/:id/load, POST /session/:id/resume ou un POST /session avec id fourni par l’appelant lorsqu’une autre inscription possède déjà cet id — renvoie 409 et :

{
  "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"
}

Déclenché lorsqu’un session/load est émis pour un id ayant déjà un session/resume en cours (ou inversement), ou lorsqu’une génération avec id fourni par l’appelant entre en concurrence avec l’une des directions de restauration. Attendez au moins Retry-After secondes et réessayez. Les concurrences de même action (load vs load, resume vs resume) sont fusionnées au lieu de générer une erreur pendant que la restauration est active.

reason distingue deux verrous partageant ce code, et l’en-tête Retry-After le suit :

La demande de restauration publique est régie par limits.sessionRestoreTimeoutMs (par défaut 60 s). Après un 504, l’id reste verrouillé jusqu’à ce que la demande ACP tardive et le nettoyage se terminent, donc un client qui continue de réessayer selon le cadencement ordinaire de 5 secondes tournerait en boucle contre un 409 qu’il ne peut pas effacer — respectez l’indice dérivé du budget accompagnant awaiting_abandoned_cleanup.

SessionWorkspaceConflictError — émis par POST /session/:id/load et POST /session/:id/resume lorsque le cwd demandé cible un espace de travail inscrit mais que le même id de session est déjà actif ou en cours de restauration par un autre runtime — renvoie 409 avec :

{
  "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"
}

Les clients doivent réessayer avec l’espace de travail propriétaire ou attendre la fin de la restauration en cours avant de restaurer l’id dans un espace de travail différent. Les concurrences de restauration dans le même espace de travail continuent d’utiliser le comportement de coalescence / restore_in_progress du pont.

SessionArchivedError est émis lorsqu’un appelant tente de charger ou reprendre une session dont le JSONL est sous chats/archive/ :

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

avec le statut 409.

SessionArchivingError est émis lorsqu’une transition d’archivage ou désarchivage de session est déjà en cours pour le même id :

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

avec le statut 409 et Retry-After: 5.

Capacités

Le démon annonce ses balises de fonctionnalité prises en charge depuis le registre des capacités serve. Les clients doivent désactiver l’interface utilisateur via features, et non via mode (conformément à la conception §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']

Les balises conditionnelles n’apparaissent que si leur condition de disponibilité de déploiement ou de runtime est remplie (voir le tableau ci-dessous). La balise permission_mediation de F3 est toujours activée et porte modes: ['first-responder', 'designated', 'consensus', 'local-only'] afin que les clients SDK puissent introspecter l’ensemble pris en charge par la compilation ; la stratégie active au runtime se trouve dans body.policy.permission.

session_startup_config annonce startupConfig: { modelServiceId, reasoningEffort? } facultatif lors de la création ordinaire et autonome. Effectuez toujours un préflight de cette balise : les anciennes routes de création ordinaire peuvent silencieusement ignorer l’objet. modelServiceId est requis (1–256 caractères) ; reasoningEffort accepte none, default, low, medium, high, xhigh ou max lorsque pris en charge par le modèle sélectionné. L’omission applique uniquement le modèle, sans réglage de raisonnement ni default implicite. L’objet ne peut pas être combiné avec le modelServiceId hérité de niveau supérieur ou une portée unique explicite et implique un nouveau fil. Le démarrage ne sauvegarde jamais les valeurs par défaut partagées ; le comportement ultérieur des sessions reste inchangé.

Le succès inclut modelApplied: true et startupConfigApplied: { modelServiceId, reasoningEffort?, effectiveReasoning? }. Le sélecteur de modèle est canonique. Seules les demandes de raisonnement explicites incluent les deux champs de raisonnement ; l’état effectif est { state: 'disabled' }, { state: 'provider-default' } ou { state: 'enabled', effort? } (le raisonnement par bascule seule n’a pas d’effort). Une structure invalide est 400 invalid_startup_config ; une sélection rejetée ou non confirmée est 422 startup_config_rejected. Un rejet définitif autonome annule son enregistrement possédé et tente de supprimer le répertoire de sortie vide avant de retourner ; un rollback d’enregistrement dont la suppression ne peut être confirmée et les échecs transitoires de démarrage conservent standalone_creation_outcome_unknown, tandis qu’un échec de suppression du répertoire est seulement journalisé et le rejet définitif est toujours retourné. Un échec de confirmation du corps de succès dans le SDK est une erreur de protocole, et non une instruction pour adopter une session récupérée.

session_scope_override est la poignée de négociation pour le champ sessionScope par requête sur POST /session (voir ci-dessous). Les anciens démons ignorent silencieusement le champ, donc les clients SDK devraient effectuer un pré-flight de caps.features pour cette balise avant de l’envoyer.

session_id_override est la poignée de négociation pour le sessionId fourni par l’appelant facultatif sur les métadonnées POST /session et ACP session/new. Les clients doivent confirmer que caps.features contient cette balise avant d’envoyer le champ car les anciens démons peuvent l’ignorer silencieusement.

persistent_workspace_registration annonce l’inscription durable pour les espaces de travail ajoutés au runtime. POST /workspaces accepte { "cwd": "/absolute/path", "persist": true } ; le succès inclut persisted: true. Les inscriptions sont limitées à l’espace de travail primaire canonique du démon sous le répertoire Qwen de l’utilisateur et sont restaurées au prochain démarrage du démon. Omettre persist préserve l’inscription locale au processus. GET /workspace-registrations liste l’ensemble souhaité stocké, et DELETE /workspace-registrations/:id oublie une entrée pour le prochain redémarrage sans retirer à chaud un runtime actif.

workspace_display_name annonce l’entrée displayName facultative sur POST /workspaces, les mises à jour de métadonnées d’espace de travail via PATCH /workspaces/:workspace, et les champs de nom d’affichage facultatifs dans les projections d’espace de travail. Les noms ne participent pas à la recherche ou au routage : id et cwd canonique restent les seuls sélecteurs, et les noms dupliqués sont autorisés.

workspace_runtime_removal annonce le retrait à chaud synchrone via DELETE /workspaces/:workspace. Les entrées de capacité d’espace de travail ajoutent un champ optionnel removable ; seules les lignes avec removable: true peuvent être supprimées. La suppression oublie également tous les alias d’enregistrement persistants pour le runtime, mais ne supprime jamais les fichiers, paramètres, transcriptions ou archives.

workspace_runtime annonce GET /workspace/runtime/status, POST /workspace/runtime/ensure et leurs équivalents /workspaces/:workspace/runtime/.... ensure n’accepte aucune sélection de capacité : il démarre ou réutilise le runtime ACP de l’espace de travail fiable sélectionné et renvoie son état de cycle de vie et son epoch de runtime monotone. Les routes principales sont possédées uniquement par le runtime principal ; les routes qualifiées résolvent uniquement le runtime enregistré sélectionné et ne reviennent jamais en arrière. Un ensure réussi renouvelle la fenêtre de keepalive de dix minutes du runtime. Le statut est en lecture seule et ne démarre jamais l’enfant. Les ensures concurrents partagent un seul démarrage physique. Un démarrage en cours ou échoué renvoie des erreurs réessayables 503 runtime_still_starting ou 503 runtime_initialization_failed. La préparation des capacités peut continuer après l’expiration du budget d’observation de l’ensure ; dans ce cas, ensure renvoie toujours le runtime actif avec un état de capacité non prêt pour le polling de statut. La capacité est annoncée uniquement lorsque tous les ponts de runtime actifs fournissent l’instantané de cycle de vie autoritaire ; un pont injecté hérité sélectionné renvoie 501 workspace_runtime_not_supported au lieu d’un état ou d’un epoch deviné.

workspace_runtime_stop annonce indépendamment l’arrêt de runtime confirmé par l’utilisateur. GET /workspaces/runtime-stop-options est une prévisualisation globale au processus en lecture seule : elle inclut le nombre d’enfants engagés, le plafond modélisé d’enfants, et pour chaque espace de travail visible ses sessions, raisons de blocage, ID de canal, epoch, jeton d’arrêt actuel et dernier reçu. Les sessions chargées ordinaires peuvent être explicitement arrêtées ; les clients ACP indépendants, les planifications activées, les travaux de planification/gestion/démarrage en attente, les tâches de mémoire, les workers, la voix et les runtimes à usage spécial sont bloqués. POST /workspaces/:workspace/runtime/stop utilise la porte de mutation stricte et uniquement le runtime fiable sélectionné. Envoyez confirmInterruptions: true, expectedChannelId, expectedRuntimeEpoch, expectedStopToken et le expectedSessionIds exact depuis la prévisualisation. Ne revenez jamais au runtime principal. La prévisualisation et chaque reçu listent les canaux ACP actifs du runtime comme channels (channelId, runtimeEpoch, executionEngine optionnel) ; un runtime peut avoir un canal par moteur d’exécution, et un arrêt couvre tous ces canaux. channelId nomme le premier canal listé et runtimeEpoch est le plus récent epoch listé, donc un canal démarré après la prévisualisation rend la confirmation obsolète.

Une réponse réussie contient state: "stopped", stopped: true et released: true, après la fermeture des sessions reconnues et la libération du registre de processus de chaque enfant listé. L’enregistrement, les fichiers et l’historique sauvegardé restent. Les réponses incluent les IDs de session affectés, interrompus, fermés et restants. Une confirmation obsolète ou bloquée est HTTP 409 (workspace_runtime_stop_stale / workspace_runtime_stop_blocked) ; une fermeture partielle est 409 workspace_runtime_stop_incomplete ; un démantèlement en cours ou échoué sans preuve de libération est 503 workspace_runtime_stop_in_progress / workspace_runtime_stop_failed ; une gestion non prise en charge est 501 workspace_runtime_stop_not_supported. Un démantèlement impur qui prouve ultérieurement la libération du registre peut renvoyer 200 avec un avertissement d’erreur ; un flush de session non confirmé renvoie toujours un résultat partiel/erreur. Le budget total d’observation/fermeture est de 60 secondes. S’il expire pendant qu’une fermeture de session est encore en vol, la réponse se stabilise avec state: "failed" et 503 workspace_runtime_stop_failed ; le nettoyage continue séparément. L’espace de travail sélectionné reste isolé et son enfant reste compté jusqu’à l’achèvement réel du nettoyage, même si l’appelant a reçu un échec. Les options en lecture seule peuvent signaler ultérieurement stopped après les fermetures reconnues et la libération prouvée, ou incomplete lorsque la persistance était non confirmée ; l’instantané d’échec déjà renvoyé ne change pas. Si le budget est plutôt épuisé entre les fermetures de sessions, la réponse se stabilise avec state: "incomplete" et 409 workspace_runtime_stop_incomplete : aucune autre fermeture ou kill forcé n’est lancé, la garde d’admission de l’arrêt est relâchée (l’enfant survivant reste compté normalement), et l’arrêt des sessions restantes nécessite une nouvelle prévisualisation et confirmation. Un refus de flush n’est pas contourné par un kill forcé des sessions restantes. La sortie racine ou une chute du nombre global de processus seul n’établit pas la libération de l’enfant sélectionné. Sous Windows, où le registre ne suit pas les groupes de processus descendants, la sortie stabilisée de la racine est la preuve de libération, donc released: true ne prouve pas que l’arbre de processus a disparu là-bas.

La confirmation répétée du dernier jeton consommé observe la même opération. Une nouvelle confirmation peut réessayer un arrêt incomplet, en faisant pivoter le jeton ; les anciens jetons consommés deviennent alors obsolètes. Si une réponse est perdue, lisez les options et faites correspondre le dernier reçu par espace de travail et jeton d’arrêt au lieu d’arrêter une autre cible. Les reçus peuvent être indisponibles après suppression, changements de confiance, ou recréation de daemon/pont ; leur absence laisse le résultat inconnu et n’autorise jamais la continuation. SDK runtimeStopOptions() et workspaceById(id).stopRuntime(confirmation) utilisent REST même avec un transport ACP et ne répètent jamais automatiquement le POST. Les abonnés de session reçoivent session_closed avec reason: "client_close" et cause: "workspace_runtime_stop" ; les sorties fatales associées à l’arrêt marquent également persistenceUnconfirmed: true. Les clients Web Shell mis à jour conservent la sélection/transcription sauvegardée et attendent un Resume explicite. Ceci est un arrêt unique, pas une suspension persistante ; un client ayant manqué l’événement peut à nouveau rivaliser pour la capacité.

Les réponses de statut et d’ensure de runtime utilisent cette forme :

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

Lorsqu’un runtime d’espace de travail a plus d’un moteur d’exécution, runtimeLive et runtimeEpoch décrivent le canal qui sert le contrôle d’espace de travail (MCP et Skills) : tant que ce canal est actif, le démarrage ou la sortie d’un autre moteur ne les modifie pas. state signale ce canal comme cold, starting ou stopping lorsqu’il n’est pas actif ; active et idle comptent le travail sur tous les moteurs.

capabilities.skills.state est not_started, starting, ready, stale, ou error ; les échecs incluent {code, message} dans capabilities.skills.error. Un catalogue Skills est à jour uniquement lorsque les valeurs runtimeEpoch de niveau supérieur et de capacité correspondent. revision ordonne la préparation des Skills au sein d’un seul epoch de runtime et ne doit pas être comparé entre epochs.

workspace_skills_config_runtime annonce les lectures Skills divisées et les mutations de configuration sous /workspace/{config,runtime}/skills et /workspaces/:workspace/{config,runtime}/skills. Le Web Shell utilise ces routes pour la gestion des Skills et, lors de la composition d’une nouvelle session, pour peupler les commandes slash depuis la config juste avant de les remplacer par un catalogue de runtime d’epoch correspondant. Lorsque la fonctionnalité est absente, les clients doivent continuer à utiliser les routes Skills héritées et ne doivent pas appeler l’ensure de runtime uniquement pour les Skills.

session_load et session_resume annoncent les routes de restauration explicite (POST /session/:id/load et POST /session/:id/resume). Les daemons plus anciens renvoient 404 pour ces chemins, donc les clients SDK devraient faire un pré-vol caps.features avant d’appeler. unstable_session_resume est toujours annoncé comme un alias déprécié pour la compatibilité avec les SDK livrés lorsque la méthode ACP sous-jacente s’appelait connection.unstable_resumeSession ; les nouveaux clients devraient faire un gate sur session_resume.

limits.sessionRestoreTimeoutMs, lorsqu’il est présent, représente le budget d’horloge murale du démon pour la requête ACP sous-jacente loadSession / unstable_resumeSession. Il s’agit d’un champ v1 additif. Le SDK TypeScript accorde au démon 10 secondes de marge côté client, et le watchdog Web Shell lui en accorde 15 ; les clients communiquant avec un démon plus ancien doivent utiliser respectivement 70 et 75 secondes.

session_transcript annonce GET /session/:id/transcript, une vue de relecture paginée en lecture seule sur le JSONL persisté des sessions actives. Elle est distincte de /load : elle n’attache pas de client, ne précharge pas l’EventBus en direct, ne crée pas de session en direct et ne modifie pas la fenêtre de relecture en direct. Les clients doivent l’utiliser lorsqu’ils ont besoin de la transcription complète sur disque pour une longue session, et continuer à utiliser /load uniquement pour la relecture en direct bornée lors de la restauration froide de l’interface utilisateur.

workspace_persisted_transcript annonce GET /workspaces/:workspace/session/:id/transcript, un paginateur local au démon fonctionnant uniquement sur les données persistées, qui ne démarre pas ACP, n’interroge pas l’état du pont en direct, ne charge pas les paramètres, ne découvre pas les capacités du projet et ne crée pas la clé de curseur persistée héritée. La balise est inconditionnelle car les primaires fiables mono-espace de travail peuvent utiliser la route plurielle ; l’autorisation de confiance par espace de travail est toujours évaluée à chaque requête. Les secondaires non fiables enregistrés peuvent lire, tandis qu’un primaire non fiable reste rejeté.

workspace_session_export annonce GET /workspaces/:workspace/session/:id/export, un export complet réservé aux entités fiables de la session active persistée de l’espace de travail sélectionné. Il est indépendant de session_export et workspace_qualified_rest_core : les démons publiés peuvent annoncer les deux anciennes balises sans implémenter la route plurielle, donc les clients doivent vérifier directement cette balise avant utilisation. La balise est inconditionnelle car un primaire fiable mono-espace de travail peut utiliser la route par id ou cwd. L’export ne résout pas un propriétaire en direct, ne démarre pas ACP, n’attache pas de client et ne bascule pas vers un autre espace de travail.

workspace_archived_session_export annonce GET /workspaces/:workspace/session/:id/archive/export, un export complet réservé aux entités fiables depuis le stockage persisté archivé de l’espace de travail sélectionné. Il est indépendant de workspace_session_export et workspace_qualified_rest_core ; les clients doivent vérifier directement cette balise avant utilisation. Une route distincte empêche un démon plus ancien d’ignorer l’intention d’archivage et de renvoyer une transcription active avec le même id.

workspace_session_live_state annonce GET /workspaces/:workspace/sessions/live-state, un instantané en mémoire uniquement réservé aux entités fiables des sessions en direct du runtime de l’espace de travail sélectionné, ainsi qu’une version de catalogue en mémoire indiquant aux clients quand un rechargement complet du catalogue persisté est justifié. Il est indépendant de workspace_qualified_rest_core : les démons publiés peuvent annoncer la capacité REST d’espace de travail plus large sans implémenter cette route, donc les clients doivent vérifier directement cette balise avant utilisation. La balise est inconditionnelle car un primaire fiable mono-espace de travail peut utiliser la route par id ou cwd ; les vérifications de confiance par espace de travail s’appliquent toujours à chaque requête, et la route n’étend pas la politique permissive de lecture du catalogue persisté des secondaires non fiables à l’état du pont en direct. La balise signifie que le point de terminaison existe ; elle ne promet pas que chaque élément en direct porte le filigrane d’activité optionnel updatedAt, qui dépend du cycle de vie.

workspace_session_live_state_batch annonce POST /sessions/live-state. Les clients vérifient cette balise une fois avant de grouper les sondages et conservent la route mono-espace de travail pour les démons plus anciens. Le lot utilise la même sémantique d’instantané en mémoire et de version de catalogue réservés aux entités fiables que la route mono-espace de travail.

Le champ top-level optionnel /capabilities sessionLiveStatePollIntervalMs annonce l’intervalle de sondage de l’état en direct à l’échelle du démon en millisecondes. Il est résolu une fois à partir de la variable d’environnement de démarrage QWEN_SESSION_LIVE_STATE_POLL_INTERVAL_MS, indépendamment des superpositions d’environnement par espace de travail. Les valeurs entières comprises entre 1000 et 2147483647 sont acceptées ; les valeurs manquantes ou invalides utilisent 5000. Web Shell consomme cet indice pour tous les sondages d’état en direct des espaces de travail et revient également à 5000 si le champ est absent ou invalide provenant d’un démon plus ancien ou incompatible. Ce champ ne modifie pas la sémantique d’instantané de la route, les rafraîchissements locaux/visibilité immédiats, ni le sondage complet du catalogue. Les clients SDK restent responsables de leurs propres temporisateurs.

slow_client_warning couvre le comportement de contre-pression SSE : (a) le démon émet une trame de flux d’événements synthétique slow_client_warning lorsque l’accumulation de trames en direct ou l’accumulation d’octets sérialisés en direct d’un abonné atteint 75 % de sa capacité, une fois par épisode de dépassement (réarmé après que les deux mesures soient descendues sous 37,5 %) ; (b) GET /session/:id/events accepte un paramètre de requête ?maxQueued=N (plage [16, 2048]) pour prédimensionner l’accumulation de trames par abonné pour les reconnexions froides face à une grande bague de relecture. La limite d’octets sérialisés est gérée par le démon (par défaut 2 MiB par abonné), concerne uniquement le direct, et n’a intentionnellement aucun paramètre de requête. La taille de la bague à l’échelle du démon est contrôlée par --event-ring-size (par défaut 8000, selon #3803 §02). Les anciens démons manquent silencieusement le comportement d’avertissement/requête — vérifiez cette balise avant de l’activer.

typed_event_schema annonce des charges utiles d’événements du démon correspondant au schéma KnownDaemonEvent du SDK. Les démons plus anciens peuvent encore diffuser des trames compatibles, mais les clients SDK doivent vérifier cette balise avant de supposer une couverture d’événements typée.

client_heartbeat annonce POST /session/:id/heartbeat. Les démons plus anciens renvoient 404 ; vérifiez cette balise avant d’émettre des battements de cœur périodiques.

session_close et session_metadata annoncent DELETE /session/:id et PATCH /session/:id/metadata. Les démons plus anciens renvoient 404 ; vérifiez ces balises avant d’exposer les options de fermeture ou de renommage.

session_organization annonce les groupes de sessions personnalisés et l’épinglage. Il ajoute GET/POST/PATCH/DELETE /workspace/:id/session-groups, PATCH /session/:id/organization, et la vue de liste organisée opt-in GET /workspace/:id/sessions?view=organized. Lorsque session_organization et workspace_qualified_rest_core sont tous deux annoncés, la mutation d’organisation qualifiée par espace de travail PATCH /workspaces/:workspace/session/:id/organization est également disponible. La mutation héritée reste réservée au primaire d’espace de travail. Les démons plus anciens renvoient 404 pour les routes de mutation/groupe et ignorent le contrat de vue organisée, donc les clients WebShell/SDK doivent vérifier ces balises avant d’afficher l’interface correspondante de regroupement ou d’épinglage.

session_archive annonce l’API d’archivage de l’état du répertoire v1 : POST /sessions/archive, POST /sessions/unarchive, et GET /workspace/:id/sessions?archiveState=active|archived. Les sessions archivées ne peuvent être chargées ou reprises jusqu’à ce qu’elles soient désarchivées. session_archive_idle_guard annonce l’option d’archivage additive requireIdle : le runtime propriétaire vérifie que le travail actif est confirmé inactif immédiatement avant de commencer la fermeture, et laisse la transcription active en place sinon. session_storage_conflict_repair annonce l’option de requête additive resolveConflicts et le compartiment de réponse resolvedConflicts décrit ci-dessous.

workspace_qualified_rest_core annonce les routes REST cœur plurielles sous /workspaces/:workspace/.... Le sélecteur se résout d’abord comme un id d’espace de travail exact, puis comme un cwd absolu encodé en URL après canonicalisation. Les démons mono-espace de travail plus récents incluent le runtime principal dans workspaces[] même lorsque multi_workspace_sessions est absent, permettant aux clients de découvrir l’id requis par les routes qualifiées par espace de travail ; les clients doivent revenir à capabilities.workspaceCwd pour les démons plus anciens qui omettent le tableau. Les routes de statut de confiance et de demande de confiance sont disponibles pour les espaces de travail non approuvés enregistrés ; la lecture du statut des hooks qualifiés (GET /workspaces/:workspace/hooks) est également servie pour les espaces de travail non approuvés enregistrés car elle rapporte la décision de confiance des hooks de projet en attente, correspondant à la mutation d’approbation qualifiée ; les routes de lecture de fichiers suivent la politique existante de lecture du système de fichiers. Les espaces de travail secondaires non approuvés enregistrés exposent également des catalogues de sessions et de groupes de sessions persistés uniquement : ces lectures ne s’attachent pas à une session, ne démarrent pas ACP et ne fusionnent pas l’état du pont en direct. Les écritures de fichiers, les mutations de catalogue et les autres routes cœur plurielles nécessitent un espace de travail approuvé sauf si une capacité distincte documente une politique plus étroite : workspace_persisted_transcript (lecture seule), ou la mutation d’octroi de confiance, qui est acceptée pour un espace de travail non approuvé enregistré que workspace_trust_grant soit annoncé ou non — cette balise indique seulement si le rechargement à chaud de la confiance est connecté, afin qu’une décision enregistrée puisse atteindre le runtime en cours sans redémarrage du démon ; elle n’indique jamais si la route est servie. Un primaire non approuvé continue de recevoir 403 { code: "untrusted_workspace" } depuis les routes de catalogue et de transcription plurielles ; les routes primaires singulières héritées conservent leur comportement de compatibilité existant. Cette balise couvre les surfaces cœur de fichiers, statut, paramètres, permissions, confiance, cycle de vie, contrôle MCP, bascules d’outils et de compétences, mémoire, CRUD d’agents d’espace de travail et stockage de sessions. Elle ne couvre pas l’authentification, la voix, les extensions, le transport ACP/WebSocket, le routage des workers de canal ou l’exportation de sessions qualifiée par espace de travail ; pré-vérifiez workspace_session_export ou workspace_archived_session_export séparément. La confiance de l’espace de travail n’est pas une ACL : un client détenant le jeton du démon peut lire toutes les surfaces d’espace de travail enregistrées autorisées par cette politique.

workspace_qualified_voice annonce les routes Voice sélectionnées par un runtime d’espace de travail approuvé : GET et POST /workspaces/:workspace/voice, POST /workspaces/:workspace/voice/transcribe, et WS /workspaces/:workspace/voice/stream. Elle est annoncée uniquement lorsque les runtimes multi-espaces de travail et l’écouteur WebSocket partagé ACP/Voice sont tous deux activés. Le sélecteur suit les mêmes règles d’id ou de cwd absolu encodé que les autres routes plurielles. Pour REST, un sélecteur inconnu retourne 400 { code: "workspace_mismatch" } et un sélecteur non approuvé retourne 403 { code: "untrusted_workspace" } ; le rejet de mise à niveau WebSocket expose le statut HTTP 400/403 correspondant sans enveloppe JSON structurée. Aucun transport ne revient au primaire. Les /workspace/voice, /workspace/voice/transcribe et /voice/stream hérités restent réservés au primaire. Les clients utilisent workspace_qualified_voice pour toutes les modalités Voice qualifiées et laissent le runtime sélectionné rapporter les erreurs spécifiques à la configuration. Les balises héritées workspace_voice, workspace_voice_transcription et voice_transcribe décrivent uniquement les routes liées au primaire et ne doivent pas masquer une configuration secondaire qualifiée.

workspace_qualified_memory annonce les routes de mémoire gérée qualifiées par espace de travail : POST /workspaces/:workspace/memory/{remember,forget,dream} met en file d’attente les tâches et GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId les relit. Elle est annoncée uniquement lorsque HTTP ACP et les runtimes multi-espaces de travail sont tous deux activés. Le sélecteur suit les mêmes règles d’id ou de cwd absolu encodé que les autres routes plurielles. Chaque espace de travail enregistré obtient sa propre voie de tâche ; la voie qualifiée du primaire est la même instance que la surface singulière /workspace/memory, donc une tâche mise en file d’attente sur l’une est lisible sur l’autre. La résolution est strictement par runtime sélectionné sans retour au primaire : un sélecteur inconnu retourne 400 { code: "workspace_mismatch" }, un sélecteur non approuvé retourne 403 { code: "untrusted_workspace" }, et un runtime inactif ou en vidange retourne 503 { code: "workspace_runtime_unavailable" }. Les lectures n’allouent jamais de voie, donc interroger un espace de travail sans tâches retourne 404 { code: "<kind>_task_not_found" }. Les ids de tâche sont limités à leur voie et ne survivent pas à une reconfiguration d’espace de travail ou à un remplacement de runtime ; un id obsolète retourne 404, et non une condition de perte de données. Lorsque HTTP ACP est désactivé, la balise n’est pas annoncée et une requête qualifiée non-primaire retourne un 501 { code: "workspace_memory_unavailable" } non réessayable, tandis que la route qualifiée primaire continue de fonctionner via la voie localement possédée.

session_lsp annonce GET /session/:id/lsp, l’instantané de statut LSP structuré en lecture seule pour les clients du démon. Les démons plus anciens retournent 404 ; pré-vérifiez cette balise avant d’exposer le statut LSP distant.

session_resources annonce GET /session/:id/resources, une paire en lecture seule d’instantanés Skill et MCP assainis construits à partir de la Config de la session en direct sélectionnée. La route est limitée au propriétaire de la session en direct : elle ne revient jamais au runtime primaire et n’infère pas les ressources de la session à partir du statut de l’espace de travail. Les objets imbriqués skills et mcp réutilisent les charges utiles correspondantes du statut de l’espace de travail, mais omettent les enrichissements d’authentification MCP, de pool, de budget d’espace de travail et d’erreurs de découverte d’espace de travail. Le statut, la découverte et la comptabilité rapportés par le gestionnaire MCP de la session sélectionnée restent présents. Les démons plus anciens retournent 404 ; pré-vérifiez cette balise avant d’afficher un catalogue de ressources de session.

session_status annonce GET /session/:id/status, le résumé du pont en direct pour une seule session par id. En plus de clientCount et hasActivePrompt, les sessions en direct exposent isWaitingForPermission, isWaitingForUserQuestion, pendingInteractionCount, et un turnError conservé après un tour échoué. L’erreur se efface lorsque le prompt suivant démarre réellement. Une session en direct qui a réglé un tour en cours dans le pont actuel porte également updatedAt, la même marque d’activité documentée sous la route d’état en direct ; parce que cette route retourne directement le résumé du pont, la valeur n’est pas fusionnée avec le mtime de la transcription persistée et peut être antérieure à celle rapportée par une liste de sessions. À la fois la réponse de statut de session unique et les listes de sessions d’espace de travail incluent turnError et pendingInteractions : actions de permission prêtes à être rendues ou questions ask_user_question ainsi que les requestId et options sélectionnables requis par les routes de vote de permission existantes. Chaque question utilisateur a un answerKey ; votez avec answers, par exemple { "0": "Polling" }, indexé par cette valeur. Les sessions persistées uniquement omettent l’état du runtime car aucun runtime n’existe. Les démons plus anciens retournent 404 ; pré-vérifiez cette balise avant d’interroger le statut d’une seule session au lieu de scanner la liste complète des sessions.

session_info annonce GET /workspace/:id/session-info et son jumeau /workspaces/:workspace/session-info. La réponse agrège les comptes de sessions actives et archivées persistées sans hydrater les métadonnées de liste. C’est un scan explicite O(n) du disque et ne doit pas être interrogé périodiquement ; les clients doivent traiter truncated: true comme un résultat de borne inférieure.

session_approval_mode_control, workspace_tool_toggle, workspace_skill_settings_toggle, workspace_skill_settings_batch_toggle, extension_batch_activation_v2, workspace_init et workspace_mcp_restart publient les routes de contrôle des mutations documentées ci-dessous. Le contrôle du mode d’approbation conserve sa porte de compatibilité non stricte. Les autres contrôles sont soumis à une porte stricte basée sur l’autorité de l’opérateur : les requêtes primaires depuis la boucle locale de confiance, authentifiées par jeton Bearer ou appariées via le Contrôle Local passent. Une requête primaire sans jeton qui atteint la porte stricte sans autorité de boucle locale de confiance renvoie 401 token_required ; les identifiants configurés manquants ou invalides et les identifiants de Contrôle Local non appariés sont rejetés plus tôt par le middleware Bearer avec un simple 401 Unauthorized. Les démons qui ne possèdent pas l’une de ces routes renvoient 404. Les balises Skill spécifiques aux paramètres sont différentes : les démons de la génération de balise retirée publient workspace_skill_toggle et workspace_skill_batch_toggle et servent leur contrat validé par catalogue aux mêmes chemins. La route à cible unique retirée peut renvoyer HTTP 404 skill_not_found ou 409 skill_not_toggleable ; la route par lots retirée renvoie HTTP 200 et place les échecs issus du catalogue dans errors[]. Effectuez une vérification préalable de chaque balise avant d’exposer son affordance, et n’inférez pas le contrat Skill spécifique aux paramètres en sondant l’accessibilité des routes. Les chemins des routes et les corps des requêtes n’ont pas changé.

mcp_guardrails (problème #4175  PR 14) couvre la surface du budget MCP : les champs clientCount / clientBudget / budgetMode / budgets[] sur GET /workspace/mcp, le champ disabledReason sur les cellules par serveur, et les indicateurs CLI --mcp-client-budget / --mcp-budget-mode. Les anciens démons omettent entièrement les nouveaux champs ; les clients SDK effectuent une vérification préalable de cette balise avant de s’appuyer sur la sémantique budgets[]. Le descripteur de registre contient également modes: ['warn', 'enforce'] pour une future exposition des modes de fonctionnalité — pour l’instant, les clients infèrent le mode à partir du champ budgetMode de l’instantané. Le refus du serveur sous le mode enforce est déterministe selon l’ordre de déclaration Object.entries(mcpServers) ; une future couche de priorité de portée (si qwen-code en adopte une) ferait passer cela à « priorité la plus basse en premier » pour refléter la convention plugin < user < project < local de claude-code.

La portée est pilotée par les capacités. Avec mcp_workspace_pool, les sessions au sein d’un même environnement d’exécution d’espace de travail partagent un pool de transport et WorkspaceMcpBudget, et l’instantané émet budgets[0].scope: 'workspace'. Différents environnements d’exécution d’espace de travail possèdent des pools indépendants. Sans la balise, chaque session ACP utilise son héritage McpClientManager, l’instantané émet scope: 'session', et N sessions peuvent chacune consommer le plafond configuré.

workspace_file_read couvre les routes de fichiers d’espace de travail texte/liste/stat/glob (GET /file, GET /list, GET /glob, GET /stat). workspace_file_bytes couvre GET /file/bytes, qui a été ajouté plus tard afin que les clients puissent pré-vérifier la prise en charge des fenêtres brutes d’octets par rapport aux démons de l’ère PR19. workspace_file_write couvre les routes de mutation de texte sensibles au hachage (POST /file/write, POST /file/edit). La balise write signifie que le contrat de route existe ; cela ne signifie pas que le déploiement actuel est ouvert aux mutations anonymes. Write/edit sont des routes de mutation strictes et nécessitent une autorité opérateur ; la boucle locale fiable sans jeton est qualifiée. workspace_file_upload couvre POST /file/upload, la route d’ingress binaire : un corps application/octet-stream limité à MAX_UPLOAD_BYTES (50 MiB) est écrit dans l’espace de travail sans jamais écraser — un nom occupé est automatiquement numéroté (name (1).ext, name (2).ext, …). C’est également une route de mutation stricte.

workspace_file_delete couvre uniquement POST /workspaces/:workspace/file/delete ; aucune route héritée primaire /file/delete n’existe. Le corps JSON est { "path": "relative/file.txt" }, et le succès renvoie { "kind": "file_delete", "path": "relative/file.txt" }. Cette route de mutation stricte supprime définitivement un fichier régulier de l’espace de travail local sélectionné de confiance. Les répertoires et les liens symboliques sont rejetés ; les fabriques non prises en charge (y compris SSH) renvoient 422. La capacité décrit la prise en charge du protocole, et non la permission de supprimer dans tous les espaces de travail. Les clients doivent également effectuer une vérification préalable de workspace_qualified_rest_core.

Lorsque workspace_qualified_rest_core est publié, la même surface de fichiers est également disponible sur /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 et /workspaces/:workspace/file/delete (la dernière route nécessite en plus workspace_file_delete).

workspace_directory_create et workspace_directory_delete publient indépendamment POST /workspaces/:workspace/directory/create et POST /workspaces/:workspace/directory/delete. Effectuez une vérification préalable de la balise de l’opération ainsi que de workspace_qualified_rest_core ; les anciens démons qualifiés peuvent ne pas posséder ces routes. Les deux sont des mutations strictes appartenant à l’environnement d’exécution local actif sélectionné de confiance, sans repli primaire ni équivalent hérité primaire. La création est exclusive sous un parent existant ; la suppression est permanente et récursive.

La même balise expose également le CRUD des agents de projet qualifiés par espace de travail sur /workspaces/:workspace/agents et /workspaces/:workspace/agents/:agentType. Ces routes plurielles lisent ou modifient uniquement les agents de niveau projet pour l’espace de travail sélectionné ; les demandes de portée global et user renvoient 400 { code: "global_scope_not_supported_for_workspace_route" }. Les routes /workspace/agents sans espace de travail conservent leur comportement actuel d’espace de travail primaire et restent la seule surface REST pour la portée des agents utilisateur.

extension_management_v2 publie un catalogue d’extensions de niveau utilisateur et une surface de mutation sur /extensions/*, ainsi que des projections d’activation d’espace de travail sur /workspaces/:workspace/extensions/*. Les artefacts sont globaux ; les routes d’espace de travail exposent uniquement les lectures de projection, les remplacements d’activation exacts et l’actualisation de l’environnement d’exécution. Les lectures peuvent cibler un espace de travail enregistré non fiable, tandis que l’activation, l’actualisation et l’installation portant sur un espace de travail nécessitent une cible fiable. Les mutations lentes utilisent des opérations locales au démon sur /extensions/operations/:operationId ; la génération du magasin, et non l’historique des opérations, fait foi lors des redémarrages et entre les démons. La capacité publiée workspace_extensions et les routes /workspace/extensions/* restent un adaptateur de compatibilité d’espace de travail primaire. Les clients doivent effectuer une vérification préalable de extension_management_v2 et ne doivent pas l’inférer à partir du mode du démon ou de workspace_qualified_rest_core.

extension_git_credentials publie les installations Git HTTPS authentifiées sur POST /workspace/extensions/install et POST /extensions/install. Les clients doivent effectuer une vérification préalable de cette balise avant d’envoyer des informations d’identification URL ou credentialPersistence ; les anciens démons rejettent les identifiants URL. La balise décrit la prise en charge du protocole backend, et non la disponibilité d’un trousseau : le mode stocké rapporte le backend sélectionné dans le résultat de l’opération terminale.

extension_local_path_install publie les sources d’Extension locales au démon sur POST /workspace/extensions/install et POST /extensions/install. Le source doit être un chemin absolu existant sur l’hôte du démon. Les chemins relatifs restent non pris en charge afin que le répertoire de travail du processus du démon ne puisse pas modifier l’identité de la source ni masquer un raccourci GitHub owner/repo. L’opération d’installation existante copie l’Extension dans le stockage géré ; elle ne lie pas la source. Les clients doivent effectuer une vérification préalable de cette balise car les anciens démons rejettent les sources locales.

extension_batch_activation_v2 ajoute PUT /extensions/activation et PUT /workspaces/:workspace/extensions/activation. Les deux acceptent 1 à 100 noms dans extensionNames, les dédupliquent sans distinction de casse tout en préservant l’ordre de première apparition, persistent les cibles modifiées en une seule génération et retournent une poignée d’opération 202 unique. Une cible n’a pas besoin d’être installée lors de la définition de enabled ou disabled : son nom crée une déclaration d’état souhaité qui est conservée lorsqu’une Extension portant ce nom est installée. La route globale accepte state: "enabled" | "disabled" et écrit V2 defaultActivation ; la route espace de travail accepte également "inherit" et applique ou efface des remplacements exacts pour le runtime fiable sélectionné. inherit ne déclare pas un nom inconnu, et un effacement entièrement inconnu signale updated: false.

extension_activation_explicit_refresh signifie que les opérations d’activation singulières et par lots se terminent après la validation durable de la politique sans rafraîchir directement les sessions actives. Les appelants nécessitant une application immédiate doivent attendre le succès de l’activation puis soumettre soit le rafraîchissement POST /workspace/extensions/refresh synchrone de l’espace de travail principal, qui retourne directement les compteurs de rafraîchissement, soit le rafraîchissement asynchrone POST /workspaces/:workspace/extensions/refresh de l’espace de travail sélectionné, qui retourne une poignée d’opération distincte. Les deux formes ne sont pas interchangeables : l’opération asynchrone enregistre la génération appliquée lorsque sa réconciliation complète du runtime se termine, tandis que la route synchrone n’enregistre rien, de sorte que le réconciliateur de génération considère toujours cet espace de travail comme en attente et rafraîchit ses sessions à nouveau lors de son prochain passage. Les appelants pouvant adresser un espace de travail spécifique doivent préférer la forme asynchrone. Un échec de rafraîchissement ne revient pas en arrière ni ne dégrade le résultat de l’activation. Les démons sans cette capacité incluent déjà le rafraîchissement du runtime dans l’activation, donc les clients de compatibilité ne doivent pas soumettre un second rafraîchissement. Le réconciliateur de génération indépendant de 30 secondes reste activé et applique normalement la politique validée lors de son prochain passage ; la réconciliation échouée est réessayée par les passages ultérieurs.

Contrat de communication Extension Management V2

Toutes les routes utilisent les règles d’authentification par jeton démon ci-dessus. X-Qwen-Client-Id est facultatif pour les routes de mutation V2 ; lorsqu’il est fourni, il doit identifier un client enregistré avec l’un des runtimes d’espace de travail cible de la mutation. :extensionId est l’identité d’extension hexadécimale minuscule de 64 caractères. :workspace se résout d’abord comme un identifiant d’espace de travail exact, sinon comme un cwd absolu encodé URL après canonisation.

Rafraîchissement explicite de l’Extension

Balise de capacité : workspace_session_refresh pour la sélection facultative de session. Les deux POST /workspace/extensions/refresh (runtime principal) et POST /workspaces/:workspace/extensions/refresh (runtime sélectionné) acceptent :

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

Omettre sessionIds préserve le rafraîchissement complet du runtime. Un tableau fourni est dédupliqué dans l’ordre de la requête, et [] ne rafraîchit aucune session ni cache d’amorçage. Les IDs doivent être des chaînes non vides. Les formes de requête invalides retournent HTTP 400 ; les IDs inconnus, y compris les sessions appartenant à un autre espace de travail, retournent HTTP 404 avant le début du travail. La propriété de session est vérifiée uniquement à l’intérieur du runtime résolu, sans repli sur le runtime principal. Les contrôles existants d’authentification, de mutation stricte, de confiance d’espace de travail et d’identité client s’appliquent.

La route principale retourne toujours HTTP 200 avec { refreshed, failed } ; la route qualifiée retourne toujours HTTP 202 avec une poignée d’opération. Les compteurs décrivent les sessions sélectionnées. Un rafraîchissement avec sessionIds ne fait pas avancer la génération appliquée à l’échelle de l’espace de travail, même si la sélection couvre toutes les sessions actuelles. La réconciliation automatique complète reste inchangée et peut rafraîchir d’autres sessions plus tard. La sélection ne crée pas de politique d’activation portée par session : les caches de runtime partagés peuvent changer, et les événements d’espace de travail restent à l’échelle de l’espace de travail.

Les clients doivent effectuer une pré-vérification de workspace_session_refresh avant de fournir le champ, y compris un tableau vide ; les anciens démons peuvent l’ignorer silencieusement. Les appels existants sans le champ ne nécessitent aucun nouveau contrôle de capacité.

État des ressources d’espace de travail

Pré-vérifiez extension_state indépendamment. Il ne prend en charge que les Skills ; il n’implique pas la gestion des ressources MCP. Les deux routes sélectionnent le runtime d’espace de travail enregistré et ne reviennent jamais au principal. GET suit les règles de confiance en lecture seule existantes ; PUT nécessite un espace de travail fiable.

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

PUT accepte 1 à 100 entrées, y compris un lot d’un seul élément. Il rejette les entrées mal formées, les noms dupliqués sans distinction de casse et les groupes non pris en charge avant la mise en file d’attente. Tous les noms doivent appartenir à l’Extension cible installée, y compris les Skills actuellement désactivés ; une cible invalide fait échouer l’opération sans écritures partielles. Une validation verrouillée unique du magasin fusionne les remplacements listés pour l’espace de travail canonique exact. Les Skills non listés et les autres espaces de travail sont préservés. Il n’y a pas d’écriture de paramètres, de déclaration de nom futur ou d’activation implicite de l’Extension parente.

GET retourne v: 1, workspaceId, workspaceCwd, extensionId, name et skills. Chaque Skill possède name, defaultEnabled, workspaceEnabled nullable, effectiveEnabled, et disabledReason/lockedScope optionnels. Le skillStates optionnel du manifeste fournit les valeurs par défaut ; les valeurs manquantes sont activées par défaut. Pour un parent actif, la priorité est la désactivation dure des paramètres, l’activation explicite des paramètres, la désactivation par défaut des paramètres, le remplacement interne de l’espace de travail, la valeur par défaut du manifeste. La désactivation interne utilise disabledReason: "default" et ne verrouille jamais les paramètres. Un parent désactivé ou supprimé ne peut pas être ranimé par un remplacement de Skill.

L’opération set_extension_state renvoie status: "updated" avec des result.resourceStates.skills ordonnés ; result.states conserve sa signification de vérification des mises à jour. L’état persisté ne garantit pas que toutes les sessions ont été actualisées. Le démon actualise uniquement les Skills et leur contexte de commandes/modèles pour le runtime cible, y compris les sessions bootstrap et actives, sans redémarrer les MCP/LSP/hooks non concernés. Les échecs d’actualisation post-commit produisent des avertissements sans retour en arrière de l’état. Les remplacements survivent aux redémarrages et aux mises à jour des Extensions et sont supprimés lors de la désinstallation. Les clients ne doivent pas recourir à l’API de paramètres Skill, qui écrit un paramètre de priorité plus élevée.

Catalogue global

La réponse du catalogue global est :

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

installType est omis lorsque aucune métadonnée d’installation n’est disponible. defaultActivation est enabled ou disabled. workspaceOverrideCount exclut les entrées inherit stockées.

La réponse de projection de l’espace de travail est :

{
  "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 est enabled, disabled ou null pour l’héritage. activationSource est default, workspace_override, legacy_path_rule ou cli_override. desiredGeneration est la génération de stockage durable ; appliedGeneration est la dernière génération enregistrée par le contrôleur comme appliquée à ce runtime d’espace de travail et peut temporairement être en retard.

L’installation nécessite un consentement explicite et une activation initiale :

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

Pour une activation initiale spécifique à l’espace de travail, utilisez { "scope": "workspace", "workspaceId": "target-workspace-id" } ; la cible doit exister et être approuvée. Les installations via le démon acceptent les sources GitHub, Git et npm. Lorsque extension_local_path_install est annoncé, ils acceptent également un chemin absolu existant sur l’hôte du démon. ref ne s’applique pas à npm, ref et autoUpdate ne s’appliquent pas aux sources locales, et registry s’applique uniquement à npm. ref, autoUpdate, allowPreRelease et registry sont facultatifs.

Lorsque extension_git_credentials est annoncé, une source Git HTTPS peut inclure des informations utilisateur, par exemple https://username:token@git.example.com/org/repository.git. credentialPersistence n’est valide qu’avec une telle source. C’est stored ou one_time et prend la valeur par défaut one_time lorsqu’il est omis. Le mode Stocké enregistre l’identifiant via le stockage hybride de secrets du démon et ne conserve que l’URL propre du dépôt dans les métadonnées d’installation, afin que l’extension reste mise à jour. Le mode Unique n’enregistre ni l’URL du dépôt ni l’identifiant et crée un snapshot non mettable à jour ; autoUpdate: true est rejeté pour ce mode. Fournir le champ sans identifiants URL, fournir des identifiants invalides, ou utiliser des identifiants avec npm, archive, local, SSH ou des sources non-Git renvoie 400.

Les réponses et opérations d’installation avec identifiants exposent credentialPersistence et peuvent exposer credentialStorage comme keychain ou encrypted_file. Les opérations uniques omettent source ; les opérations stockées peuvent renvoyer la source propre. Les entrées de statut/catalogue instantanées omettent la source, définissent credentialPersistence sur one_time et rapportent not updatable. La mise à jour échoue avec extension_not_updatable ; un secret stocké indisponible échoue avant l’accès réseau avec extension_credential_unavailable.

Les requêtes d’activation globale et d’espace de travail PUT utilisent le même corps :

{ "state": "enabled" }

state est enabled ou disabled. Les requêtes de mise à jour, désinstallation, vérification des mises à jour, effacement de l’activation et actualisation n’ont aucun corps requis.

Les requêtes d’activation par lot utilisent les noms d’Extension :

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

Le lot d’espace de travail accepte également "state": "inherit". Les résultats globaux terminaux contiennent name et defaultActivation ; les résultats d’espace de travail contiennent name, workspaceActivation (null pour héritage) et effectiveActivation. Les noms malformés rejettent la requête ; les conflits avec les identités Store existantes échouent atomiquement sans commit partiel. Une cible inherit inconnue n’est pas persistée, car effacer un remplacement ne doit pas fabriquer une déclaration d’activation par défaut ni remplacer un consentement d’installation ultérieur.

Chaque mutation asynchrone acceptée renvoie :

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

Les mutations qualifiées par espace de travail utilisent le même chemin de sondage global /extensions/operations/:operationId. L’historique des opérations est local au processus, ne conserve qu’un nombre limité d’entrées terminales et est perdu au redémarrage du démon ; les clients doivent relire le catalogue ou la projection d’espace de travail et comparer les générations lorsqu’un id d’opération disparaît.

Un instantané d’opération a cette forme :

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

status passe de queued à running, puis à succeeded, succeeded_with_warnings ou failed. Pendant l’exécution, phase est preparing, committing ou reconciling. Le succès terminal peut inclure result avec status égal à installed, enabled, disabled, updated, uninstalled, checked ou refreshed ; les résultats de réconciliation peuvent contenir en plus refreshed, failed et error, tandis que les résultats d’activation par lot contiennent des results ordonnés. Les vérifications de mise à jour renvoient result.states, indexé par nom d’extension, avec des valeurs telles que checking for updates, update available, up to date, not updatable ou error. Les identifiants et en-têtes d’autorisation ne sont jamais des champs d’opération.

Un commit durable suivi d’un nettoyage incomplet ou d’une réconciliation de runtime n’est pas signalé comme une mutation échouée. Il renvoie succeeded_with_warnings et préserve le résultat engagé :

{
  "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."
    }
  ]
}

Les avertissements workspaceId et code sont facultatifs ; workspaceCwd et error sont toujours présents. Les clients doivent afficher les avertissements, actualiser leur catalogue/projection et ne doivent pas retenter aveuglément la mutation durable.

Les échecs de validation et d’autorisation sont des erreurs HTTP synchrones utilisant { "error": "...", "code": "..." } lorsqu’un code stable existe. Les cas importants sont 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 et 429 extension_queue_full. La validation d’installation renvoie également 400 pour des options source/ref/registry invalides, un consentement manquant, ou une activation initiale manquante/invalide. Une mutation qui échoue après 202 est représentée, tout en étant conservée dans l’historique des opérations, avec status: "failed", error et un code stable facultatif ; les codes courants incluent extension_prepare_timeout et extension_conflict. Un HTTP 404 pour une opération n’implique pas de rollback car l’historique des opérations n’est pas durable.

daemon_status annonce GET /daemon/status, l’instantané diagnostic consolidé en lecture seule de l’opérateur documenté ci-dessous.

daemon_update annonce la surface globale au processus GET /daemon/update, POST /daemon/update/prepare et POST /daemon/update/restart.

scheduled_task_gate annonce le facultatif gate sur POST et PATCH /scheduled-tasks, ainsi que gate et gateStatus sur les vues de tâche. Une porte est une commande shell que la session propriétaire exécute à chaque déclenchement, en dehors du modèle : une sortie 0 avec une sortie livre le déclenchement avec cette sortie attachée, une sortie 0 sans rien sur stdout le saute, et une sortie non nulle est signalée lorsque la porte commence à échouer, pas à chaque déclenchement. gateStatus.lastOutcome est quiet, delivered, failed ou blocked.

• Une porte nécessite une tâche récurrente : POST avec recurring: false, ou un PATCH qui définit une porte sur un one-shot ou transforme une tâche gated en one-shot, répond 400 gate_requires_recurring ; une tâche déjà dans cet état conserve ses autres modifications. Une porte mal formée (vide sur POST, seulement un commentaire, plus de 2048 caractères, un caractère NUL ou un surrogate UTF-16 non apparié, un wrapper shell tel que bash -c '…', ou toute partie mise en arrière-plan avec &) répond 400 invalid_gate. La vérification & est lexicale et best-effort ; en cas de doute, elle refuse (un & dans un commentaire, un corps heredoc ou (( … ))), et une porte qui passe est signalée failed lorsqu’elle sort sans rien sur stdout alors qu’une partie en arrière-plan maintient encore son stdout (en dehors du sandbox shell bwrap, dont l’espace de noms PID termine cette partie avec la commande). Sur PATCH, gate: null ou gate: "" efface la porte et son condition.
• Une tâche héritée protégée par une condition refuse toute clé gate dans un PATCH avec 409 task_legacy_unsupported, donc un client envoie gate uniquement lorsqu’il la modifie.
• Une porte écrite via ces routes ne porte aucune confirmation de la part de la session. Elle s’exécute sans surveillance uniquement là où un appel monitor de la même commande s’exécuterait sans demander : sous une règle allow Monitor(...) ou Bash(...) enregistrée, comme commande en lecture seule, ou dans une session auto ou yolo. Une règle deny la bloque dans tous les modes et le mode plan la bloque ; un déclenchement bloqué se stabilise blocked.
• Les clients ne doivent pas envoyer gate à un démon sans cette balise : un tel démon le jette sur POST et répond à un PATCH uniquement-gate avec 400 empty_patch.

autofix_pr_watches annonce GET /autofix-pr/watches (l’espace de travail principal) et GET /workspaces/:workspace/autofix-pr/watches (un espace de travail enregistré et fiable). Chacun répond aux /autofix-pr watches du clone de l’espace de travail comme qwen autofix-pr status les liste, lus à partir des fichiers des watches sous le worktree principal du clone (.qwen/tmp), chacun ouvert sans suivre de lien et sans blocage. Aucun verrou n’est pris, GitHub n’est pas interrogé, et aucune commande git n’est exécutée sauf git worktree list, qui trouve le clone. La réponse est { v: 1, available, root?, now?, watches, unreadable? } : available est false, sans watches, lorsqu’aucun dépôt git n’est trouvé pour l’espace de travail (ou si git ne peut pas s’y exécuter), et root est le worktree principal du clone, le même pour deux espaces de travail d’un seul clone. Une watch porte les champs de status (Section 6.10 de la conception /autofix-pr) mais thisSession, worktreePath, pushTarget, gitTrusted et worktreeWork ; son session est la session qui la possède, qui peut être aucune session de ce démon. Arrêter une watch relève de la compétence (/autofix-pr stop <n> dans la session qui la possède) ; ces routes ne changent rien.

Balises conditionnelles. Ces balises de fonctionnalité sont annoncées uniquement lorsque leur bascule de déploiement, leur câblage d’exécution ou leur condition de disponibilité est active. La présence de la balise signifie que le comportement documenté est disponible ; l’absence signifie soit un démon plus ancien précédant la balise, soit un démon actuel où cette condition est fausse. Actuellement :

Live Voice utilise l’endpoint Web Shell (realtime_voice_web, WS /live/web) sur toutes les plateformes par défaut. L’Hôte natif macOS est en opt-in : seul un démon macOS démarré avec QWEN_SERVE_LIVE_NATIVE_HOST=1 annonce realtime_voice, enregistre WS /live/host et installe l’Hôte lorsque Live est activé. Sans cela, /live/setup rapporte nativeHost: false avec une erreur install non réessayable, et POST /live/setup/install et POST /live/setup/launch répondent 409 live_native_host_unavailable.

Un Host navigateur répond host.capture_visual uniquement pendant que l’utilisateur partage un écran avec la page, ce que la page signale dans son hello comme selfChecks.screenShare. Le partage est un acte séparé et explicite — le modèle demande en cours de tour, et getDisplayMedia nécessite un geste utilisateur — donc la page maintient le flux et prend une image par requête. Sans rien de partagé, elle répond success: false immédiatement plutôt que de laisser la requête expirer.

Parce qu’une page ne peut pas écrire sur le système de fichiers du démon, elle envoie uniquement le JPEG. Le démon ignore tout screenshotPath rapporté par un bail navigateur et stocke l’image elle-même, sous un nom qu’il choisit, dans le même répertoire de capture privé auquel un Host natif écrit. Un Host natif persiste toujours son propre PNG et passe le chemin, comme auparavant.

mcp_guardrails n’est pas dans ce tableau conditionnel — c’est une balise toujours active, annoncée chaque fois que le binaire supporte les nouveaux champs de budget /workspace/mcp, indépendamment du fait que l’opérateur ait configuré un budget. Les opérateurs qui n’ont pas défini --mcp-client-budget obtiennent quand même les nouveaux champs (avec budgetMode: 'off', budgets: []).

mcp_guardrail_events (problème #4175  PR 14b) annonce les événements de push SSE typés qui font surface aux franchissements d’état du budget MCP sans boucle de sondage. Deux types de trames arrivent sur GET /session/:id/events :

• mcp_budget_warning — se déclenche une fois au franchissement ascendant de 75 % de reservedSlots.size / clientBudget. Se réarme seulement après que le ratio est passé sous 37,5 % (MCP_BUDGET_REARM_FRACTION). Reflète l’hystérésis slow_client_warning de la PR 10, mais au niveau du gestionnaire plutôt qu’au niveau de l’arriéré par abonné. Charge utile : { liveCount, reservedCount, budget, thresholdRatio: 0.75, mode: 'warn' | 'enforce' }. Se déclenche dans les modes warn et enforce ; jamais dans le mode off.
• mcp_child_refused_batch — se déclenche à la fin de chaque passage discoverAllMcpTools* lorsqu’un ou plusieurs serveurs ont été refusés, ET en tant que lot de longueur 1 sur le chemin de refus de génération différée readResource. Charge utile : { refusedServers: [{ name, transport, reason: 'budget_exhausted' }, ...], budget, liveCount, reservedCount, mode: 'enforce' }. mode est le 'enforce' littéral car le mode warn ne refuse jamais.

Les deux événements vivent dans l’anneau de rejeu SSE par session (ils portent un id) afin qu’un client se reconnectant avec Last-Event-ID reprenne à travers eux ; le snapshot à GET /workspace/mcp reste la source de vérité pour l’état après une déconnexion prolongée. Toujours actif une fois annoncé — il n’y a pas de bascule conditionnelle. L’état du reducer SDK (DaemonSessionViewState) expose mcpBudgetWarningCount, lastMcpBudgetWarning, mcpChildRefusedBatchCount, lastMcpChildRefusedBatch pour les adaptateurs qui veulent une UI simple de type retard.

Routes

Les clients peuvent détecter la fonctionnalité session_turn_status et interroger GET /session/:id/turns/current ou GET /session/:id/turns/:promptId. Ces routes nécessitent la Session propriétaire active et ne chargent ni ne scannent jamais un autre espace de travail. Les résultats réglés sont des enregistrements de transcript best-effort lus depuis la branche active avec un scan borné ; prompt_not_found signifie qu’aucun résultat n’a été trouvé dans la file active, la superposition terminale de 64 entrées ou la fenêtre active bornée. resultText est la réponse brute finale du modèle parent après la dernière frontière d’outil, avant la réécriture optionnelle du message, et peut être absente. Les résultats dépassant 32 768 unités de code UTF-16 incluent resultTruncated: true et resultCode: "RESULT_TEXT_TRUNCATED".

GET /health

Sonde de vivacité. La forme par défaut retourne 200 {"status":"ok"} si l’écouteur est actif — bon marché, sans accès au pont, adapté aux sondes de vivacité k8s/Compose à haute fréquence.

Passez ?deep=1 (accepte aussi ?deep=true ou ?deep nu) pour une sonde globale au démon qui agrège les compteurs de pont à travers chaque runtime d’espace de travail géré, y compris un espace de travail encore en vidange (informatif uniquement, pas une vraie vérification de vivacité) :

{
  "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 et activePrompts sont des sommes. activeWork est vrai quand n’importe quel runtime a un prompt accepté mais non réglé (y compris un prompt attendant en FIFO), un Agent en arrière-plan en cours d’exécution, une notification de terminal d’Agent mise en file/en cours, un shell en arrière-plan ou un travail de workflow géré par la Session, ou un tour de Session possédé par un enfant. Le maintien agrégé session couvre le traitement des objectifs et des cron, la mutation de l’historique, et les continuations Monitor mises en file ou en cours d’exécution ; les prompts au premier plan restent possédés par le démon. Les Monitors en cours d’exécution, les suggestions de suivi et les processus externes que le registre de shell ne peut plus suivre restent hors du champ. Il est scopé par session : le travail au niveau canal sans session attachée encore — une génération en vol, une restauration en attente, la découverte ou l’authentification MCP — n’est pas compté, donc activeWork peut lire faux alors que le démon refuse encore de récupérer ce canal. Ne lisez pas ce champ comme “le démon est récupérable” ; il décrit uniquement le travail possédé par la session. activeWorkReporting indique quelle partie de ce booléen est réellement garantie : full quand chaque session vivante est couverte par un rapport frais d’un enfant qui rapporte toutes les catégories requises, none quand aucune session n’a négocié le reporting, et partial pour tout entre les deux — y compris un snapshot périmé ou un enfant négocié qui omet une catégorie requise. Un snapshot plus vieux que trois intervalles de rapport cesse de compter comme couverture : ce n’est pas un rapport indiquant que la session est inactive, donc la session revient à être lue comme retenue, exactement comme si l’enfant n’avait jamais rapporté. Le nettoyage automatique ordinaire est également désactivé pour un enfant négocié mais incomplet ; un enfant qui ne comprend pas shell ou session ne peut pas autoriser en toute sécurité la fermeture conditionnelle selon le prédicat complet actuel. Les enfants historiques complètement non supportés conservent le comportement de nettoyage legacy, et la fermeture explicite, le kill, l’arrêt et la sortie de canal restent des opérations forcées. activeWorkStaleMs est l’âge du snapshot le plus ancien sur lequel repose le booléen parmi les sessions couvertes, et est 0 quand aucune session n’est couverte ; c’est diagnostique, car la fraîcheur est déjà graduée dans activeWorkReporting par le démon (seul le démon connaît la cadence négociée de chaque canal). La note est calculée une fois sur chaque runtime géré plutôt que par runtime puis combinée — un runtime sans sessions est vacuusement complet, et traiter cela comme preuve permettrait à un espace de travail vide de garantir les sessions non rapportées d’un autre espace de travail. lastActivityAt est la dernière heure d’activité d’espace de travail non-nulle et idleSinceMs est dérivée de ce même snapshot. channelAlive signifie qu’au moins un canal d’espace de travail géré est vivant ; cela ne signifie pas que chaque espace de travail est sain. connectedClients et l’optionnel rateLimitHits restent des compteurs globaux au démon plutôt que des sommes par espace de travail.

Les contrôleurs de redémarrage doivent considérer le démon comme occupé quand :

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

Supprimer le troisième terme rend activeWork === false indistinguable de “aucun enfant ne m’a dit quoi que ce soit”, ce qui est le seul cas où agir dessus est dangereux. Les réponses inconnues et les sondes échouées doivent également empêcher le redémarrage. activePrompts reste un signal de compatibilité indépendant.

Ces champs sont un cache d’observation, pas un bail de redémarrage : même une réponse fraîche, entièrement notée et vide décrit le moment où elle a été échantillonnée, et le travail peut commencer immédiatement après. La règle ci-dessus réduit substantiellement le risque d’un mauvais redémarrage mais ne l’élimine pas — la sécurité stricte nécessite une barrière de préparation au redémarrage qui arrête l’admission de nouveau travail, confirme la vidange, et seulement ensuite s’arrête.

⚠️ La sonde approfondie est informative, et non une véritable vérification de vivacité ou un bail de récupération atomique. Les enfants ACP négociés publient des instantanés du travail actif à l’échelle du canal selon une cadence négociée, et le démon évalue leur fraîcheur en activeWorkReporting — mais il ne tue jamais un canal en raison d’un rapport manquant, car le silence d’une session n’est pas la preuve que le processus est mort. La vivacité du transport et la détection des Agents bloqués sont des mécanismes distincts. connectedClients compte les connexions REST SSE, et non tous les transports ACP. Utilisez des échantillons répétés et une fermeture gracieuse pour la récupération des ressources inactives ; utilisez /daemon/status authentifié pour le diagnostic du transport et par espace de travail. Si un getter d’exécution gérée lève une exception, la santé approfondie échoue de manière sécurisée avec 503 {"status":"degraded","reason":"aggregation_failed"} plutôt que de retourner des totaux partiels, et le journal du démon identifie l’environnement d’exécution de l’espace de travail défaillant. Lors de l’amorçage, avant que le registre d’exécution ne soit prêt, il retourne 503 {"status":"degraded","reason":"bootstrap"} avec Retry-After: 1. Pour la vivacité de l’écouteur, utilisez le défaut /health sans ?deep.

Auth : requise sur les liaisons non-loopback et lorsque le loopback est durci avec --require-auth. Sur une liaison loopback ordinaire (127.0.0.0/8, localhost, ::1, [::1]), /health est enregistré avant le middleware bearer afin que les sondes k8s/Compose dans le pod n’aient pas besoin de porter le jeton. Sur non-loopback (--hostname 0.0.0.0 etc.) ou loopback durci, la route est enregistrée après le middleware bearer et renvoie 401 sans jeton valide — sinon, un appelant non authentifié pourrait sonder des adresses arbitraires pour confirmer qu’un qwen serve existe, une fuite d’informations de faible sévérité qui se combine mal avec le scan de ports. Le refus CORS + la liste blanche Host s’appliquent toujours à l’exemption loopback ordinaire.

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

Ces routes authentifiées gèrent l’installation de Qwen Code du démon, indépendamment de l’espace de travail sélectionné. Elles utilisent toujours REST, y compris depuis les clients SDK avec un transport de session ACP. La capacité daemon_update annonce le protocole ; la disponibilité est déterminée par l’état renvoyé.

GET vérifie les versions sans les télécharger ni les activer. Les vérifications réussies sont mises en cache pendant 15 minutes et les erreurs pendant une minute ; ?refresh=true demande une nouvelle vérification. Les vérifications simultanées partagent une seule recherche. La réponse contient state (available, up-to-date, installing, ready, restarting, unavailable ou error), canInstall, optionnellement currentVersion et latestVersion, ainsi que instructions et message optionnels. currentVersion identifie le démon en cours d’exécution, y compris après la préparation d’une mise à jour. Les méthodes d’installation non prises en charge peuvent signaler available avec canInstall: false et des instructions manuelles.

Les mises à jour automatiques nécessitent un cycle de vie CLI réel avec POSIX process.execve, une installation autonome ou une installation globale npm/pnpm/yarn/bun exécutant le lanceur publié (un préfixe npm appartenant à root est inclus, car la préparation n’écrit jamais dans le préfixe global), et des paramètres opérateur autorisant general.enableAutoUpdate. Les serveurs intégrés, Windows, les environnements d’exécution Node non pris en charge et le mode développement signalent unavailable. Seuls les paramètres globaux/système s’appliquent ; les paramètres de l’espace de travail ne peuvent pas activer l’installation. La connexion doit utiliser le listener principal et son jeton d’exécution du démon, ou le déploiement loopback explicitement approuvé sans jeton. Les navigateurs couplés et les connexions Local Control signalent unavailable, car leurs identifiants ou leur listener ne survivraient pas au redémarrage ; leurs mutations de mise à jour renvoient 403 update_connection_unsupported.

Les deux routes POST exigent l’autorité de l’opérateur du démon via la porte stricte de mutation et n’acceptent aucun paramètre. Le serveur choisit la version, la destination et le lanceur ; les clients ne peuvent pas fournir de version ni de commande.

• POST /daemon/update/prepare démarre un téléchargement en arrière-plan et renvoie 202 avec state: "installing". Cela ne modifie pas l’installation active. Interrogez GET jusqu’à ce que l’état soit ready ; les préparations répétées partagent la même opération et une mise à jour préparée renvoie 200. En l’absence de mise à jour automatique disponible, cela renvoie 409 update_unavailable.
• POST /daemon/update/restart nécessite une mise à jour préparée, sinon il renvoie 409 update_not_ready. Il répond avec 202 et state: "restarting" avant d’activer la mise à jour, de fermer gracieusement le démon et de remplacer le processus par le lanceur mis à jour. Les clics répétés partagent un seul redémarrage. Après avoir répondu, le démon re-résout la version actuelle une fois : si elle est plus récente que celle préparée et qu’un clic unique la couvre, la version plus récente est préparée et la charge utile préparée est écartée, afin qu’un démon de longue durée aboutisse sur la dernière version actuelle plutôt que sur celle qui était la dernière lors de sa première préparation. La charge utile plus récente est engagée avant que la précédente ne soit écartée, et cet écartement est fait au mieux : un échec d’écartement laisse des données sur le disque mais n’isole jamais la charge utile plus récente ni ne revient à une version potentiellement supprimée à moitié. latestVersion signale ensuite la cible plus récente tandis que state reste restarting. Une re-résolution ou une préparation échouée applique la version préparée à la place ; le clic n’est jamais bloqué sur la version en cours d’exécution par une défaillance du registre. Le remplacement conserve le PID, le répertoire de travail, les options CLI, le port lié et le jeton de démon effectif, efface les anciennes épingles de version et ne rouvre pas de navigateur. Le client interroge GET jusqu’à ce que currentVersion change, puis recharge le document à l’URL capturée lorsque la mise à jour a été demandée. Parce que la préparation s’exécute après 202 et peut prendre plusieurs minutes, le client mesure son délai de redémarrage à partir d’une indisponibilité continue, et non du clic : un démon qui continue de répondre fonctionne encore. Un plafond absolu généreux (20 minutes) sécurise un démon qui reste joignable mais ne quitte jamais restarting. Il se situe au-dessus de toute la chaîne de préparation, et non au-dessus d’une constante de timeout unique : un téléchargement d’archive autonome essaie OSS puis GitHub séquentiellement avec un budget de cinq minutes chacun, et les récupérations de checksum et de signature ajoutent jusqu’à deux minutes supplémentaires, donc une re-préparation peut passer environ douze minutes à télécharger et vérifier avant l’activation ; l’enfant npm géré est plafonné à dix. Chaque chemin d’abandon garde une entrée réessayable à l’écran, car un démon bloqué continue de signaler restarting, que le contrôle n’affiche pas autrement. Une fois le redémarrage confirmé, restarting reste actif jusqu’à ce que le processus soit remplacé, donc un démon joignable qui signale tout autre état avec un currentVersion inchangé signifie que le remplacement n’a pas abouti sur la nouvelle build ; le client cesse d’attendre, publie cet état stabilisé et signale un échec plutôt que d’attendre indéfiniment un changement de version. Cette vérification s’applique uniquement aux interrogations initiées après la confirmation : les demandes de statut et de redémarrage sont indépendantes, donc une interrogation commencée plus tôt peut livrer un instantané pré-redémarrage ensuite, et interpréter cela comme un démon stabilisé rapporterait un faux échec et supprimerait le rechargement qu’une mise à jour réussie doit encore à l’utilisateur. La validation du lanceur autonome s’exécute avant la fermeture des services ; une vérification échouée laisse le démon en marche. Les échecs après le début de la fermeture ou pendant le remplacement du processus ne sont pas garantis de récupérer.

Web Shell vérifie et prépare automatiquement les mises à jour disponibles prises en charge en arrière-plan, et affiche son bouton de mise à jour adjacent à la version lorsqu’une mise à jour préparée est prête ou lorsqu’une mise à jour disponible comporte des instructions manuelles. Dans l’état d’instructions manuelles, le bouton ouvre un popover avec les instructions issues de la vérification et ne prépare ni ne redémarre jamais. La préparation et la disponibilité survivent aux rechargements du runtime de l’espace de travail. Une mise à jour préparée épingle sa cible : le GET de polling, y compris ?refresh=true, continue de signaler la mise à jour latestVersion préparée et ne retélécharge jamais, afin qu’un démon qui reste actif sur plusieurs versions ne génère pas de téléchargements superflus en arrière-plan. Seul le redémarrage résout à nouveau la cible. L’arrêt normal du démon supprime le téléchargement préparé. Les échecs d’activation maintiennent le démon en cours d’exécution et signalent error ; la vérification suivante après la mise en cache de l’erreur d’une minute peut préparer un nouveau téléchargement pour une nouvelle tentative. La désactivation des mises à jour automatiques supprime la disponibilité et nettoie le téléchargement avant qu’un redémarrage puisse commencer. Une fois qu’un redémarrage est en cours, il n’est pas perturbé : tant que l’état est restarting, les routes de statut, de préparation et de redémarrage renvoient toutes sans consulter le paramètre opérateur, et le nettoyage à l’arrêt est une opération vide, de sorte qu’une remise en place qui prend plusieurs minutes ne peut pas voir sa charge utile retirée sous ses pieds. Cliquer sur le bouton dans l’état prêt redémarre explicitement l’intégralité du démon et interrompt ses sessions actives.

GET /daemon/status

Diagnostics opérateurs en lecture seule. Contrairement à /health, il s’agit d’une API normale du démon : elle est enregistrée après l’authentification par jeton et la limitation de débit, y compris sur les liaisons loopback. Paramètre de requête :

• detail=summary (par défaut) lit uniquement l’état du démon en mémoire.
• detail=full inclut également les diagnostics de session en direct, les diagnostics de connexion ACP, les compteurs de flux d’appareils d’authentification et les sections de statut de l’espace de travail.
• tout autre detail retourne 400 { "code": "invalid_detail" }.

summary n’interroge intentionnellement pas les méthodes de statut de l’espace de travail, ne démarre pas d’enfant ACP et ne crée pas de session. full interroge chaque section de l’espace de travail indépendamment ; un délai d’attente ou une exception marque uniquement cette section comme unavailable et ajoute un problème workspace_status_unavailable.

Forme de la réponse :

{
  "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
    }
  }
}

Les réponses multi-espaces de travail incluent également des lignes workspaces[] de niveau supérieur avec { id, cwd, displayName?, primary, trusted }. Le nom d’affichage optionnel est omis lorsqu’il n’est pas défini et reste purement présentationnel ; les consommateurs de statut doivent continuer à utiliser id ou cwd pour corréler les runtimes.

runtime.perf est facultatif. Lorsqu’il est présent, il signale uniquement le retard de la boucle d’événements du processus du démon, les échantillons d’attente de la file FIFO des invites et les compteurs d’octets des tuyaux enfants du démon ; le retard de la boucle d’événements de l’enfant ACP n’est pas inclus dans /daemon/status.

status est error si un problème a une sévérité d’erreur, warning si un problème a une sévérité d’avertissement, sinon ok. Les codes de problème sont stables et incluent 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 et workspace_status_unavailable. Pendant la courte fenêtre après que l’écouteur est prêt mais avant que le runtime complet soit monté, /daemon/status peut signaler daemon_runtime_starting ; si le montage asynchrone du runtime échoue, il signale daemon_runtime_failed tandis que les routes de runtime non-statut renvoient 503.

runtime.activity signale l’activité des prompts à l’échelle du démon. activePrompts compte les sessions ayant un prompt en cours. pendingPrompts compte tous les prompts acceptés qui ne sont pas encore terminés, y compris le prompt en cours d’exécution et les prompts en attente dans la file FIFO. queuedPrompts compte les prompts en attente dans la file FIFO qui ont été acceptés mais non dispatchés. lastActivityAt est l’horodatage ISO 8601 du dernier début/fin de prompt ou de création de session ; null lorsque le démon n’a jamais traité aucune activité depuis le démarrage. idleSinceMs est calculé à partir de lastActivityAt au moment de la génération de la réponse.

limits.memory est additif et rapporte les chiffres de mémoire résolus du démon : un enforced: false requis, un objet childHeap (mode : off, observe, ou admit ; admissionEnforced, vrai uniquement pour les admit gérés ; maxConcurrentChildren et perChildCeilingMb, tous deux null sous mode: 'off', qui ne modélise rien — et perChildCeilingMb ajoute null partout où aucune partition ne peut être modélisée dans modeled.minChildHeapMb — soit le pool ne peut couvrir un enfant à ce plancher, soit le plafond tomberait en dessous une fois plafonné à modeled.legacyChildCeilingMb, qui est floor(available / 2) et tombe donc sous le plancher sur un hôte de moins de 1024 Mo. Il n’est jamais 0, et maxConcurrentChildren est 0 dans ces cas, car un hôte qui ne modélise aucune partition donne une réponse calculée plutôt qu’un modèle absent ; et refusals, les créations qui auraient dépassé la limite modélisée), configuredBudgetMb, effectiveBudgetMb (la valeur configurée plafonnée à la mémoire cgroup/hôte résolue), budgetSource (flag / derived), availableMemoryMb, availableMemorySource (constrained / host), insufficientMemory, et un objet modeled contenant rootReserveMb, childPoolMb, minChildHeapMb, maxChildHeapMb, et legacyChildCeilingMb (un modèle conservateur du plafond qu’un enfant ACP reçoit aujourd’hui, qui peut se situer sous la figure réelle). runtime.memory rapporte également registeredWorkspaces (le nombre d’enregistrements — entrées d’espace de travail non supprimées, y compris celles en vidange, en transition ou bloquées ; pas un nombre d’enfants actifs), activeAcpChildren (enfants ACP gérés par le démon avec un canal actif non mourant — inclut les entrées en transition ou bloquées, mais exclut un espace de travail dont le kill a commencé même si l’enfant n’a pas quitté ; pas les workers de canal, les descendants MCP, ni les réservations de création non attachées), childRssCoverage (active_children — chaque enfant ACP avec un canal actif, qui est l’ensemble que activeAcpChildren compte ; les démons plus anciens envoient primary_only), un objet children décrit ci-dessous, et un objet modeled contenant recommendedShareAtRegisteredMb (null quand aucun espace de travail n’est enregistré) et recommendedShareAtActiveMb (null quand aucun enfant n’est actif). Chaque part est plafonnée au plafond hérité des enfants, et planchée au tas minimal des enfants seulement lorsque le plafond le permet — sur un petit hôte, le plafond se situe sous le plancher, donc part × nombre peut dépasser le pool d’enfants. Lisez une part comme consultative, pas comme une partition du pool. Le dimensionnement du tas des enfants reste consultatif : aucun argument de création d’enfant ne découle de ces valeurs. admit optionnel applique le nombre concurrent d’enfants modélisé, tandis que observe par défaut enregistre uniquement les refus potentiels. runtime.memory.committedAcpChildren compte les réservations ACP gérées et les enfants attachés, y compris les enfants en cours de terminaison jusqu’à la libération du registre ; il est null lorsque le registre géré est indisponible. childHeap modélise une partition fixe de modeled.childPoolMb — chaque enfant recevrait la même perChildCeilingMb, donc le total modélisé reste dans le pool plutôt que de s’accumuler comme le ferait une part par création. Lisez refusals uniquement comme une pression d’admission : un compte de 0 ne signifie pas que la partition est sûre à appliquer, car les enfants tournent sur le plafond beaucoup plus grand dérivé de l’hôte, donc une charge de travail nécessitant plus d’espace ancien que perChildCeilingMb est saine ici et ne échouerait que si la partition était appliquée. Deux autres raisons pour lesquelles un compte non nul ne signifie pas nécessairement une pression de capacité : la décision d’admission compte un enfant en cours de terminaison jusqu’à sa sortie, donc sur un démon déjà à maxConcurrentChildren chaque remplacement de canal réserve un refus pendant la fenêtre de chevauchement ; et sur un hôte trop petit pour modéliser une partition, maxConcurrentChildren est 0, donc refusals égale le nombre total de créations ACP, avec insufficientMemory comme champ qui l’explique. Dans admit, un modèle à zéro emplacement fait échouer le démarrage. Un démon entièrement géré confronté à l’épuisement de la capacité peut récupérer un ACP vide le moins récemment utilisé sans sessions actives ni travaux en attente, attendre la libération suivie, puis réessayer l’admission une fois avant de créer. Les sessions chargées restent protégées ; l’enregistrement de l’espace de travail et l’historique sauvegardé sont conservés. Le compteur refusals compte les tentatives d’admission rejetées, y compris un rejet initial suivi d’une récupération réussie, pas les échecs finaux visibles par l’utilisateur. La capacité épuisée renvoie REST HTTP 503 avec code: "acp_child_capacity_exhausted", maxConcurrentChildren, et committedAcpChildren (excluant la réservation rejetée), sans Retry-After. ACP JSON-RPC utilise -32603 avec data.errorKind portant ce code, data.httpStatus: 503, et les mêmes compteurs. Une annulation de création autonome pré-dispatch vérifiée conserve standalone_creation_rolled_back, son ID de session et sa répétabilité, et imbrique le code de capacité et les compteurs sous capacity ; les résultats incertains de création conservent leurs sémantiques de récupération existantes. Les clients doivent arrêter les tentatives automatiques de capacité et préserver le brouillon ou la session sélectionnée pour une nouvelle tentative manuelle. Sur le chemin normal runQwenServe, le budget est résolu avant la création de l’application bootstrap, donc limits.memory est déjà peuplé pendant la fenêtre bootstrap. Il est null uniquement sur les chemins qui ne résolvent aucun budget (comme le direct-embed contournant runQwenServeImpl). Le type SDK autorise null, donc les clients corrects s’en accommodent.

runtime.memory.children est additif dans ce bloc et rapporte le RSS agrégé parmi les enfants nommés par childRssCoverage : rssBytes (leur somme de RSS auto-rapportée), sampled (combien ont produit une lecture), et oldestReadingAgeMs (l’âge de la lecture la plus ancienne dans la somme, afin qu’un appelant puisse dire à quel point ses parties ont été prises séparément). Le dénominateur pour sampled est le frère activeAcpChildren, non répété dans le bloc ; quand sampled est inférieur, rssBytes est un plancher plutôt qu’un total. L’échantillonnage est conditionné par un watcher SSE/WS actif, donc une demande de statut contre un démon dont personne ne stream rapporte sampled: 0 même avec des enfants actifs — activeAcpChildren à côté rend cet écart visible, et rssBytes: 0 avec sampled: 0 ne signifie jamais un zéro mesuré. oldestReadingAgeMs est null quand rien n’a été échantillonné et aussi quand chaque contributeur est un pont antérieur au champ, donc cela ne signifie jamais “frais”. Lisez la somme comme un sur-comptage et un sous-comptage à la fois : sommer le RSS par processus double-compte les pages partagées par les enfants, tandis que chaque enfant ne rapporte que son propre processus, donc ses descendants MCP et chaque worker de canal sont manquants. Ce n’est pas la mémoire de l’arbre du démon. Le champ est optionnel dans le miroir SDK car les démons rapportant primary_only ne l’envoient jamais.

runtime.memory.children.heap est additif au sein de ce bloc et rapporte les pics historiques de la génération ancienne V8 pour chaque enfant ACP, agrégés comme un maximum, non une somme : peakOldGenerationBytes, peakLiveSetBytes, peakTotalHeapBytes, majorGcCount, majorGcMs, unclassifiedSpaceNames et reported. Un plafond de tas s’applique par enfant et les pics ont été atteints à des moments différents, donc un total ne répondrait à aucune question ; chaque champ est un maximum indépendant parmi les enfants déclarants, non le portrait d’un seul enfant, et un plafond par enfant est évalué contre chaque axe individuellement. reported compte combien de sampled ont contribué, et est inférieur lorsque certains enfants précèdent l’apparition des champs. Chaque chiffre en octets couvre la génération ancienne — ce que --max-old-space-size borne réellement — et non old_space seul, car un enfant peut épuiser son plafond avec old_space à quelques mégaoctets tandis que large_object_space contient tout. peakOldGenerationBytes représente les octets engagés et augmente avec le plafond attribué à l’enfant, donc lisez-le comme une borne supérieure sur ce dont la charge de travail a besoin plutôt que comme sa nécessité réelle ; peakLiveSetBytes est ce qui survit après un GC majeur et ne bouge pas avec le plafond, ce qui en fait la figure capable de dire qu’un enfant ne peut pas tenir dans un seul ; lisez-le comme une borne supérieure plutôt que comme un ensemble vivant exact, car les entrées de GC arrivent de manière asynchrone et tout ce qui est alloué entre la collecte et la lecture est compté. peakLiveSetBytes est égal à 0 jusqu’à ce qu’un GC majeur soit observé, ce qui est une absence plutôt qu’une mesure. unclassifiedSpaceNames est l’union des espaces de tas qu’aucun enfant déclarant n’a pu classer ; V8 renomme et ajoute des espaces entre les versions, un espace inconnu est exclu des sommes, et l’exclusion sous-estime — donc un tableau non vide signifie que les chiffres en octets sont incomplets et ne doivent pas être lus comme une mesure complète. L’objet entier est null, jamais un objet remis à zéro, lorsqu’aucun enfant échantillonné n’a signalé l’un d’eux ; sans watcher SSE/WS attaché, rien n’est échantillé du tout, c’est donc un état courant plutôt qu’un cas limite. Tout cela est observationnel : rien ici ne dimensionne un enfant, refuse un spawn ou déplace limits.memory.enforced hors de false.

runtime.memory.pressure est additif au sein de ce bloc et rapporte la pression mémoire propre au processus racine du démon : mode (off / observe), level (normal / soft / hard / critical), source (rss / heap / unknown), ratio, et les six chiffres bruts dont proviennent les ratios — rssBytes, rssRatio, availableBytes, heapUsedBytes, heapRatio, heapLimitBytes. ratio est le plus grand entre rssRatio et heapRatio, et source nomme lequel c’était ; les égalités sont rapportées comme rss. availableBytes est limits.memory.availableMemoryMb en octets — délibérément la figure détectée du cgroup/hôte plutôt que effectiveBudgetMb, car ce qui termine le processus est la limite réelle, non un nombre politique de l’opérateur. source: "unknown" signifie qu’aucun dénominateur n’était mesurable et ne doit pas être lu comme sain ; level est normal dans ce cas uniquement parce qu’il n’y a rien à classifier. Les chiffres couvrent le processus racine du démon uniquement : ils sont propres à ce processus memoryUsage(), donc la croissance des enfants ne les modifie pas. runtime.memory.children les rapporte séparément, et aucune de ces figures n’est la mémoire de l’arbre de processus. Les deux modes rapportent le bloc entier ; seul observe remonte en plus l’avertissement daemon_memory_pressure sans chemin dans le récapitulatif de statut, donc off laisse le status de niveau supérieur inchangé. Rien ne se corrige dans aucun mode. Le champ est optionnel dans le miroir SDK car les démons livrés avec runtime.memory avant son existence envoient le bloc sans lui.

limits.maxRegisteredWorkspaces est additif et rapporte le plafond résolu d’enregistrement utilisateur (par défaut 256, configurable de 1 à 256). limits.maxChannelControlWorkspaces rapporte le plafond indépendant de propriétaire contrôle/récupération de 25 sur le démon standard, même lorsque les canaux sont désactivés. Les contrôleurs personnalisés annoncent ce champ seulement quand ils l’appliquent. Ces champs sont présents dans les réponses bootstrap et ready ; les anciens démons peuvent les omettre. Le contrôleur de canal rejette les unions transitoires de propriétaires dépassant son plafond avec 409 channel_control_workspace_limit_reached avant de construire les candidats workers ; une union initiale au démarrage dépassant le plafond échoue au lancement avant que l’écouteur ne soit publié, donc elle n’a pas de surface HTTP. La capacité d’enregistrement ne détermine pas le délai du canal SDK.

limits.maxTotalSessions est additif. null signifie que le plafond effectif global de nouvelles sessions du démon est désactivé. Lorsque la capacité d’enregistrement résolue (par défaut 256, configurable via QWEN_SERVE_MAX_WORKSPACES ou maxRegisteredWorkspaces intégré) dépasse 25 et que --max-total-sessions est omis, le démon standard utilise un total fixe de 800, même avec un seul espace de travail au démarrage. À des capacités d’enregistrement de 25 ou moins, plusieurs espaces de travail au démarrage/restaurés avec un maxSessionsPerWorkspace fini dérivent le total effectif une seule fois comme maxSessionsPerWorkspace * workspaceCount sur ce même nombre de démarrages-plus-restaurations ; un seul espace de travail au démarrage ou restauré conserve un défaut illimité. Les limites totales explicites, y compris les valeurs désactivées, ont priorité. L’enregistrement dynamique ultérieur ne recalcule pas le total. Les intégrations directes createServeApp doivent fournir leur propre politique d’admission partagée. Lorsqu’il est défini, il limite la création de nouvelles sessions à travers le démon et rapporte les échecs de limite totale avec la forme d’erreur existante session_limit_exceeded plus scope: "total".

runtime.channel.live signale le canal de pont ACP à l’intérieur du démon. Ce n’est pas le worker de l’adaptateur de canal. Les canaux gérés par le démon utilisent runtime.channelWorker, dont state est l’un de disabled, starting, running, exited, failed ou stopped. Lorsqu’un worker atteint running puis se termine, /daemon/status maintient le démon en ligne et signale le code de problème d’avertissement channel_worker_exited.

Le démarrage du worker de canal géré par le démon à partir d’une sélection explicite qwen serve --channel ... reste fail-fast et prime sur les paramètres de démarrage persistés. Un démarrage sans indicateur restaure serve.channels depuis chaque espace de travail enregistré fiable, chacun contribuant à la liste dans ses propres paramètres de portée d’espace de travail. Les noms restaurés forment une sélection dont les propriétaires sont résolus comme d’habitude, l’espace de travail ayant listé un nom brisant une égalité de propriété autrement ambiguë. Cette attribution au démarrage dure aussi longtemps que le démon fonctionne : un PUT /workspace/channel réactivant un tel nom le résout de la même manière qu’au démarrage, même si la sélection a été arrêtée entre-temps. Un nom contribué par un espace de travail non primaire est supprimé, avec un journal l’identifiant, lorsqu’il ne peut pas être résolu, afin qu’une entrée obsolète d’un espace de travail ne bloque pas les autres ; un nom listé par l’espace de travail primaire fait encore échouer la restauration dans son ensemble, qu’un autre espace de travail le liste ou non. all reste réservé au primaire : il est ignoré, et signalé, partout ailleurs.

Un espace de travail non primaire fiable enregistré après le démarrage restaure également son propre serve.channels, chargeant le runtime du canal et réservant le bail du service de canal si rien d’autre ne l’a fait. Cette restauration :

• se produit une fois par exécution du démon — enregistrée dès que l’espace de travail demande quoi que ce soit — afin qu’une suppression et une ré-enregistrement ultérieurs, ou une rematérialisation de confiance, n’annulent pas un opérateur qui a arrêté l’un de ces canaux entre-temps ;
• ne se produit pas sous une sélection explicite --channel, qu’aucun espace de travail enregistré plus tard n’étend ;
• ne se produit pas après que DELETE /workspace/channel a cessé d’héberger, jusqu’à ce qu’un PUT /workspace/channel engage à nouveau une sélection ou que le démon redémarre ;
• laisse une sélection engagée all telle quelle ;
• ajoute les noms de cet espace de travail à la sélection validée en une seule modification, avec une restauration tardive à la fois. Contrairement au démarrage, qui ignore un nom qu’il ne peut pas héberger et conserve le reste, un nom qui ne peut pas être attribué laisse la liste entière de cet espace de travail non restaurée, l’erreur étant journalisée et signalée comme décrit ci-dessous.

L’enregistrement n’attend pas du tout le contrôle des canaux. La restauration est mise en file d’attente sur la voie de contrôle des canaux et la réponse est écrite sans attendre, il en va de même pour la réconciliation déclenchée par un changement d’enregistrement ou de confiance pour les canaux que le démon héberge déjà. Un worker qui ne devient jamais prêt retarde donc uniquement les travaux de canal mis en file derrière lui, jamais un autre enregistrement ni une réconciliation de confiance. L’inconvénient est qu’un 201 de POST /workspaces ne signifie pas que les canaux de cet espace de travail sont opérationnels, ni qu’un canal déjà hébergé qu’il possède a terminé son redémarrage ; consultez GET /workspace/channel pour cela.

Sans sélection explicite, une restauration serve.channels au démarrage, ou un enregistrement comme celui décrit ci-dessus, le chargement de l’exécution des canaux reste paresseux.

Les noms de démarrage stockés doivent être non vides, ne comporter aucun espace blanc initial ou final, et ne contenir aucun caractère de contrôle ou invisible non sûr. Les entrées invalides sont ignorées individuellement et journalisées par index de tableau ; le démarrage ne les tronque pas en d’autres noms d’instance ni ne réécrit les paramètres. Les arguments du worker utilisent --channel=<value>, préservant un tiret initial comme partie intégrante du nom.

Un champ de démarrage invalide ou une erreur de validation ou de bail avant le démarrage des workers saute la restauration automatique, avec une journalisation identifiant serve.channels, tandis que les paramètres non liés restent effectifs. Un échec du démarrage du worker permet au démon de continuer après la réussite du nettoyage. Les délais d’expiration globaux du démarrage de l’exécution et les arrêts de workers non confirmés suivent le chemin existant d’échec de démarrage ; le bail reste détenu tant que la terminaison du worker n’est pas confirmée. La gestion des canaux signale les paramètres de démarrage persistés et l’état réel de l’exécution.

Certains noms serve.channels que le démon n’a pas activés sont signalés plutôt que simplement journalisés. Un tel nom ne rejoint jamais la sélection validée, donc aucun instantané de worker ne le porte. Trois cas sont signalés :

• une sélection de démarrage configurée dont le worker n’a pas réussi à démarrer, sur le chemin de démarrage qui maintient le service du démon sans ses canaux ;
• un nom écarté par le résolveur de propriété au démarrage lors de son attribution à un espace de travail, signalé contre chaque espace de travail qui le listait ;
• chaque nom encore non hébergé après l’échec de la restauration d’une inscription tardive.

Ils apparaissent dans deux endroits :

• /daemon/status signale un avertissement channel_restore_failed par espace de travail, nommant chaque canal avec son erreur. C’est la surface complète, et elle est présente également dans la réponse de bootstrap, qui est la seule qui existe pendant que les enregistrements de démarrage sont écrits. Au plus 64 canaux sont nommés par espace de travail, chaque nom étant limité à 128 caractères, avec and <n> more lorsque la liste est plus longue ;
• le GET /workspaces/:workspace/channels de cet espace de travail liste le canal avec runtime: { state: "error", lastError } au lieu de stopped, où lastError est l’erreur de démarrage propre de l’adaptateur lorsque le worker en a signalé une pour ce canal, sinon l’erreur de la tentative. Cette surface est construite à partir de la portée des paramètres de canal propres à l’espace de travail, elle ne peut donc porter qu’un nom défini par cette portée — un nom que aucune configuration d’espace de travail enregistrée ne configure, ou dont la configuration se trouve dans un autre espace de travail, n’a pas de ligne ici et est signalé uniquement sur /daemon/status.

Tout le reste qui laisse un nom serve.channels non hébergé est diagnostiqué uniquement dans le journal du démon : un nom perdu parce que la liste entière était illisible ou invalide, la liste d’un espace de travail non principal écartée parce que le principal a sélectionné all, une restauration tardive sautée parce que la sélection validée est all, et la liste d’un espace de travail distant (SSH). Consultez les journaux du démon pour ceux-ci.

Un signalement dure jusqu’à ce que le canal soit hébergé — par cet espace de travail ou par une restauration ultérieure depuis un autre — jusqu’à ce que son espace de travail ne soit plus enregistré, ou jusqu’à ce qu’un opérateur agisse : démarrage, arrêt ou redémarrage POST sur le canal, PUT/DELETE /workspace/channels/:name, ou un PUT/DELETE /workspace/channel qui modifie la sélection. PUT /workspace/channels/:name/startup ne le dégage pas : il réécrit serve.channels sans rien dire sur la tentative qui a échoué. Le signalement est conservé en mémoire : un démon redémarré restaure à nouveau et signale ce que cette tentative a fait. Le texte de l’erreur est expurgé des identifiants et limité de la manière dont le journal du démon le rend.

Après qu’un worker ait atteint l’état prêt, les sorties inattendues sont redémarrées par le superviseur de service selon une politique bornée : jusqu’à 3 tentatives de redémarrage dans une fenêtre de 5 minutes, avec un backoff de 1 s, puis 5 s, puis 15 s. Le worker envoie des battements de cœur IPC toutes les 15 s ; si aucun battement n’est observé pendant 45 s, le superviseur traite le worker comme obsolète, le tue, enregistre staleHeartbeatAt, et utilise le même chemin de redémarrage.

runtime.channelWorker peut inclure des champs opérationnels additifs : requestedChannels, pid, startedAt, exitCode, signal, error, restartCount, lastExitAt, lastRestartAt, nextRestartAt, lastHeartbeatAt, staleHeartbeatAt, startupFailures et startupFailuresTruncated. Chaque échec de démarrage possède channel, phase (actuellement connect), un code optionnel fourni par l’adaptateur et un message avec les identifiants masqués. Au maximum 64 échecs sont conservés pour la génération actuelle du worker ; le drapeau de troncature indique que davantage d’échecs ont été observés. code est diagnostique et ne constitue pas une classification stable entre adaptateurs. restartCount est le nombre total de tentatives de redémarrage effectuées par ce processus serve ; un worker en cours d’exécution avec restartCount > 0 est sain sauf si un autre problème s’applique. Un worker en cours d’exécution dont les requestedChannels incluent des noms absents de channels signale channel_worker_partial_connect.

Sur un démon multi-espaces de travail (--workspace répété), runtime inclut en plus channelWorkers[] — une entrée par espace de travail propriétaire, chacune étant un instantané channelWorker annoté avec workspaceId, workspaceCwd et primary. channelWorker reste peuplé comme l’instantané de l’espace de travail principal pour des raisons de compatibilité. Les démons mono-espace de travail omettent channelWorkers[].

Contrôle des canaux géré par le démon

La capacité channel_control annonce la ressource de sélection d’environnement d’exécution. La ressource est globale au démon bien que son chemin de compatibilité utilise le préfixe singulier /workspace. Les sélections d’environnement d’exécution ne sont pas persistées et ne modifient pas l’option --channel du démon au démarrage.

GET /workspace/channel retourne un instantané immuable du gestionnaire :

{
  "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 est null lorsqu’il est désactivé. pendingSelection n’est présent que pendant une mutation. transition est l’un de idle, starting, reconciling, stopping ou rolling_back.

PUT /workspace/channel est strict-gated et accepte exactement une sélection :

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

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

Les noms sont nettoyés et dédupliqués sans tri ; un tableau de noms vide est invalide. all reste limité à l’espace de travail principal. Une modification de désactivé à activé retourne 201 ; un PUT idempotent ou un remplacement retourne 200. La réponse est { changed, replaced, partial, state }. Une sélection égale maintient les workers sains en place, mais récupère une sélection égale dont le worker est arrêté ou en échec.

DELETE /workspace/channel est strictement contrôlé et idempotent. Il retourne { changed, state } ; un état réussi est désactivé. POST /workspace/channel/reload est également strictement contrôlé, relit les paramètres, résout à nouveau les groupes d’espaces de travail et force la réconciliation de la sélection engagée. Il retourne 409 channel_worker_not_enabled lorsqu’il est désactivé. La capacité channel_reload est annoncée dynamiquement uniquement lorsque le gestionnaire possède une sélection engagée et rechargeable.

Chaque activation, remplacement, rechargement, arrêt et arrêt du démon entre dans une voie de cycle de vie FIFO unique. GET n’attend pas cette voie. Les groupes d’espaces de travail dont la sélection ordonnée n’a pas changé restent en ligne. Les échecs de remplacement tentent d’arrêter les nouveaux workers démarrés et de restaurer la sélection engagée précédente. Les clients doivent inspecter rolledBack, rollbackError et state car le nettoyage ou la restauration peuvent également échouer. Le démon conserve le bail PID du service de canal tout au long d’une transaction et ne le libère qu’après confirmation de la sortie de chaque enfant pertinent.

Les erreurs de contrôle stables sont :

• 400 invalid_channel_selection, channel_workspace_mismatch, ou ambiguous_channel_workspace
• 403 untrusted_workspace
• 409 channel_service_conflict, channel_worker_not_enabled, ou channel_control_workspace_limit_reached
• 500 channel_worker_stop_failed
• 502 channel_worker_start_failed, avec rolledBack et un rollbackError optionnel expurgé des identifiants
• 503 daemon_draining

Les écritures strictes provenant d’une requête principale sans jeton qui atteint la porte sans autorité de boucle locale fiable retournent 401 token_required avant l’exécution du code de contrôle. Des identifiants configurés manquants ou invalides et des identifiants Local Control non appariés sont rejetés plus tôt avec un simple 401 Unauthorized. Les requêtes principales via boucle locale fiable s’exécutent normalement. Une fois qu’une requête commence, la déconnexion du client HTTP n’annule pas la transaction de cycle de vie ; les clients peuvent réessayer le même PUT en toute sécurité.

Pour 502 channel_worker_start_failed, la réponse peut également inclure startupFailures[] et startupFailuresTruncated. Chaque échec ajoute le workspaceCwd fiable du worker tenté. Ces champs décrivent la transaction échouée, tandis que state décrit l’état actuel après rollback ; un GET ultérieur ne conserve pas la tentative échouée. Un worker partiellement connecté retourne plutôt un succès et expose ses échecs dans l’instantané du worker. Un démarrage explicite --channel sans adaptateur connecté fait échouer le démarrage. Un échec de démarrage dérivé des paramètres est journalisé et permet au démon de continuer après la réussite du nettoyage, sous réserve du délai global de démarrage de l’environnement d’exécution. L’impossibilité de confirmer le nettoyage conserve le comportement normal d’échec de démarrage et le bail de service.

qwen channel status sans --daemon-url continue de lire les métadonnées du fichier pid ; avec --daemon-url, il lit GET /workspace/channel. Pendant une fenêtre de redémarrage, le fichier pid possédé par serve reste réservé, mais workerPid est omis afin que les clients n’affichent pas un processus worker obsolète. Sur un démon multi-espaces de travail, le fichier pid contient également un tableau additif workers[] (par espace de travail workspaceId / workspaceCwd / channels / workerPid actif) tandis que le niveau supérieur channels (union) et workerPid (principal) restent peuplés pour les lecteurs anciens ; les démons mono-espace de travail conservent la forme originale à worker unique. stdout/stderr du worker sont transférés dans le journal du démon avec les jetons bearer, les valeurs d’environnement sensibles du worker et les identifiants URL du proxy masqués.

Gestion des canaux d’espace de travail

La capacité channel_management annonce la configuration de Canal et la gestion de l’environnement d’exécution à portée d’espace de travail. Les routes singulières /workspace ciblent l’environnement d’exécution principal. /workspaces/:workspace résout l’environnement d’exécution exact enregistré et fiable et ne revient jamais à l’environnement d’exécution principal.

La découverte en lecture seule utilise :

• 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 renvoie le journal des événements Channel de l’espace de travail résolu sous forme de { "events": [...], "truncated": boolean } avec Cache-Control: no-store, ainsi qu’un membre optionnel channelLinkMeta : une carte du nom d’instance de canal vers les métadonnées de lien non secrètes (type et baseUrl, présents uniquement lorsqu’ils sont configurés comme chaînes de caractères, et pour les canaux GitHub un webOrigin résolu — l’origine de l’interface web que les clients doivent concaténer directement au lieu de la dériver à nouveau depuis la racine de l’API). Les métadonnées sont résolues à partir des paramètres système + utilisateur + espace de travail fusionnés utilisés par les workers de canal — la liste de gestion locale à la portée ne contient pas les canaux configurés dans une autre portée — et filtrées pour les canaux dont le cwd résolu appartient à l’espace de travail interrogé, afin qu’un espace de travail ne reçoive jamais les métadonnées de canal d’un autre espace de travail. Cela permet aux clients de lier les lignes du journal (par exemple, une référence PR ou issue GitHub) même pour les canaux hérités des paramètres utilisateur ou système. Le membre est entièrement omis lorsqu’aucun canal n’est résolu, et les anciens démons ne l’envoient jamais ; une erreur de lecture des paramètres se dégrade en son absence plutôt qu’en échec de la lecture du journal. Chaque événement enregistre ce qu’un Canal a fait — un message entrant accepté ou ignoré (avec la raison machine : reason_filter, mention_required, duplicate, un rejet par filtre d’expéditeur, github_api_error), un fil GitHub dont le traitement a échoué et qui sera relu (failed avec github_api_error : une erreur GitHub, ou une erreur locale lorsque le canal ne peut pas lire ou écrire son propre état ou qu’une des tâches du fil est inachevée), un résultat de publication, une transition de tâche entrante, ou un résultat de sondage — et ne porte jamais le texte du message. Un sondage GitHub qui filtre plus de 20 notifications journalise les 20 premières individuellement et une ligne supplémentaire reason_filter dont le detail.filtered compte le reste, afin qu’un curseur de sondage épinglé ne puisse pas inonder le journal avec des répétitions du même lot. Tant que le curseur est maintenu, un commentaire relu par le sondage est journalisé comme duplicate ou mention_required une fois par fenêtre, et un fil défaillant comme github_api_error lors de son premier sondage défaillant dans la fenêtre et tous les dix sondages défaillants suivants (une limite de débit ou une erreur d’identifiants : son premier et tous les dix sondages suivants), et une fois lorsqu’il est ignoré. Les lignes une fois par fenêtre sont suivies sous jusqu’à 8 192 clés ; une ligne dont la clé ne tient plus est journalisée à chaque sondage. Paramètres de requête : limit (1-500, défaut 100), type (valeurs séparées par virgules inbound, outbound, task, poll), channel (répéter le paramètre une fois par nom d’instance), et since (ISO 8601). La route ne nécessite aucune autorité opérateur. Les lectures de journal sont asynchrones et bornées : le journal actuel plus un fichier tournant par Canal, 256 KiB par fichier, 4 MiB par requête, 32 fichiers par requête, du plus récent au plus ancien. Les métadonnées de lien lisent également de manière synchrone un instantané sans effets de bord des paramètres fusionnés (quelques petits fichiers JSON, résolus contre l’environnement effectif du runtime) ; c’est une décoration best-effort, donc toute erreur omet le membre au lieu de faire échouer la lecture du journal. truncated est vrai lorsque la limite d’enregistrements ou une borne de lecture a tronqué le résultat, y compris un journal plus haut que la fenêtre de fin par fichier. Un espace de travail sans journal encore renvoie une liste vide ; un répertoire de portée illisible répond par une erreur 5xx plutôt qu’une liste vide.

Le catalogue marque les types pris en charge par cette API de gestion avec manageable: true. Les instantanés d’instances incluent une révision, des métadonnées de présence de secrets expurgées, l’état de démarrage et l’état d’exécution ; les secrets littéraux ne sont jamais renvoyés. Les instantanés de Canal utilisent Cache-Control: no-store.

Les descripteurs de champ peuvent exposer des métadonnées d’objets imbriqués via properties. Les descripteurs numériques peuvent utiliser exclusiveMinimum pour une borne inférieure ouverte et maximum pour une borne supérieure inclusive. Un nombre stocké hors d’une borne nouvellement déclarée est toujours accepté lorsque le client le renvoie inchangé, donc déclarer une borne ne bloque pas les modifications non liées d’un canal existant ; une valeur réellement modifiée par le client doit satisfaire les deux bornes. Les descripteurs de chaîne et de secret peuvent utiliser multiline pour demander aux clients une zone de texte multiligne ; les types de descripteurs ne l’autorisent que sur les champs de niveau supérieur. Les clients qui ne rendent pas un type de champ annoncé doivent préserver sa valeur de configuration existante au lieu de la forcer ou de la supprimer, et un client qui rend un champ multiline dans un contrôle mono-ligne doit préserver la valeur stockée verbatim au lieu de réécrire sa valeur d’entrée débarrassée des sauts de ligne. Les champs objets ne peuvent pas être requis, et les propriétés imbriquées ne peuvent pas être des secrets ou des champs résolus par environnement ; ces protocoles de gestion restent uniquement au niveau supérieur. Une propriété imbriquée required n’est appliquée que si son objet parent est présent dans l’écriture ; omettre l’objet parent laisse ses exigences imbriquées non vérifiées. Les écritures remplacent la valeur stockée de chaque champ intégralement, donc préserver un objet signifie renvoyer l’objet stocké ; le démon ne fusionne pas les objets partiels.

Les écritures de configuration utilisent une concurrence optimiste et la porte stricte d’autorité opérateur :

• PUT /workspace/channels/:name
• DELETE /workspace/channels/:name
• PUT /workspace/channels/:name/startup
• les routes /workspaces/:workspace/... équivalentes

Chaque mutation de paramètres inclut expectedRevision. Les requêtes d’upsert contiennent un objet config et peuvent contenir des opérations explicites sur les secrets : preserve, replace, ou clear. Une configuration de Canal ne peut pas sélectionner un répertoire de travail hors de l’espace de travail résolu.

Les actions d’exécution sont strictement limitées aux requêtes POST vers .../channels/:name/start, stop ou restart. Elles opèrent uniquement sur le worker possédé par l’espace de travail résolu.

La gestion du couplage n’est disponible que pour les instances configurées avec la politique d’expéditeur pairing ou la politique de groupe :

• GET .../channels/:name/pairing-requests
• POST .../channels/:name/pairing-requests/approve avec { "code": "..." }
• GET .../channels/:name/pairing-approvals
• DELETE .../channels/:name/pairing-approvals avec soit { "senderId": "..." } soit { "groupId": "..." }

Toutes les routes de couplage nécessitent une autorité stricte de l’opérateur et utilisent Cache-Control: no-store. Les demandes, approbations et révocations sont limitées à l’instance Channel et à l’espace de travail sélectionnés. Les demandes en attente incluent un sujet utilisateur ou groupe typé ; les demandes de groupe conservent également l’expéditeur qui a initié la demande. Les instantanés d’approbation contiennent senderIds et groupIds car les listes blanches ne persistent pas les noms d’affichage. La révocation d’un utilisateur ou d’un groupe inconnu renvoie 404 channel_pairing_approval_not_found.

Livraison de Canal et Notify

channel_delivery annonce un support de livraison immédiate au mieux (best-effort). C’est une capacité du protocole, non un signal de santé du worker. La livraison ne démarre jamais un worker manquant, ne bascule pas sur un autre espace de travail, ne retente pas, ne persiste pas une boîte d’envoi et ne rejoue pas les notifications historiques.

Notify direct contourne Agent et Session et attend une tentative d’envoi :

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"
    }
  }
}

Les deux routes utilisent la porte de mutation stricte. La route qualifiée résout uniquement un espace de travail enregistré et fiable. Le succès est 200 {delivered:true,deliveryId}. delivered:true signifie que la promesse d’envoi Channel s’est résolue ; cela ne prouve pas l’acceptation par le fournisseur, la réception par l’utilisateur ni un accusé de lecture. La validation des réponses spécifiques au fournisseur et la cohérence des sémantiques des raisons d’erreur entre les adaptateurs IM sont hors du périmètre de ce contrat V1. Les erreurs sont 400 channel_delivery_invalid, 503 channel_worker_unavailable ou channel_delivery_queue_full, 504 channel_delivery_timeout, et 502 channel_delivery_rejected ou channel_delivery_failed. Un délai d’expiration a un résultat inconnu et n’est pas retenté. Il n’y a volontairement pas d’endpoint distinct de test de connectivité : un appel Notify normal constitue le test de bout en bout.

L’événement de résultat rejouable contient uniquement la corrélation et le statut assaini :

{
  "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."
  }
}

Une finalisation Prompt réussie vide omet les champs d’erreur :

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

source est prompt ou scheduled ; status est delivered, failed ou skipped. skipped signifie que le tour éligible s’est terminé avec succès mais que son dernier bloc de réponse assistant sans outil était vide ou composé uniquement d’espaces. Le démon consomme l’autorisation de livraison et publie l’événement sans résoudre de Worker Channel. La corrélation planifiée utilise taskId et firedAt. L’événement ne contient jamais d’IDs de cible, de texte de message, de credentials ou de secrets webhook.

Sécurité : la réponse n’inclut jamais de jetons bearer, d’IDs client, d’IDs complets de connexion ACP, de codes utilisateur de flux d’appareil ou d’URLs de vérification. Les deux niveaux de détail peuvent inclure des champs additifs daemon.runId, daemon.logMode et daemon.logHealth. summary omet le chemin du journal du démon et les détails de perte ; full peut inclure logPath, logIssues, logDroppedRecords et logDroppedBytes pour les opérateurs authentifiés. La journalisation fichier dégradée ajoute l’avertissement daemon_log_degraded sans chemin au récapitulatif de statut normal.

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
    }
  ]
}

Contrat stable : lorsque v s’incrémente, la structure des trames a changé de manière incompatible avec les versions précédentes.

protocolVersions décrit les versions du protocole serve que le démon peut utiliser. current est la version de protocole préférée du démon et supported est l’ensemble compatible. Les clients qui nécessitent un protocole spécifique doivent vérifier supported ; l’interface utilisateur spécifique aux fonctionnalités doit toujours se baser sur features. Ajouté à v=1 : les anciens démons v=1 omettent ce champ, donc les clients SDK ciblant des builds plus anciens doivent le traiter comme optionnel.

modelServices est toujours [] en Phase 1. L’agent utilise son unique service de modèle par défaut et ne l’énumère pas sur le réseau. La Phase 2 remplira ce champ à partir des adaptateurs de modèles enregistrés afin que les clients SDK puissent construire des sélecteurs de services ; d’ici là, NE comptez PAS sur ce champ pour être non vide.

workspaceCwd est le chemin absolu canonique pour l’espace de travail principal du démon. Utilisez-le pour omettre cwd sur POST /session (la route revient à ce chemin principal) et pour maintenir la compatibilité avec les anciens clients mono-espace de travail. Ajouté à v=1 : les démons v=1 pré-§02 omettent le champ — les clients ciblant des builds plus anciens doivent vérifier s’il est nul avant de l’utiliser.

workspaces[] liste tous les environnements d’exécution enregistrés. Les nouveaux démons mono-espace de travail incluent l’environnement d’exécution principal même si multi_workspace_sessions est absent, afin que les clients puissent découvrir l’identifiant stable requis par les routes qualifiées par espace de travail ; les anciens démons peuvent omettre le tableau. Chaque entrée est { id, cwd, displayName?, primary, trusted, removable? }. displayName est purement présentationnel et omis lorsqu’il n’est pas défini. Le premier/principal espace de travail reste reflété par workspaceCwd ; les nouveaux clients choisissent un environnement d’exécution non principal en passant l’cwd de cette entrée à POST /session. Les espaces de travail non fiables sont annoncés pour le diagnostic mais rejettent la création de nouvelles sessions avec 403 untrusted_workspace jusqu’à ce que la confiance change. removable est présent sur les démons qui prennent en charge la suppression d’environnements d’exécution et n’est vrai que pour les environnements d’exécution secondaires dynamiques au niveau du processus ou restaurés depuis la persistance.

session_worktree_persistence_v1 signifie que le démon peut persister et vérifier la propriété des worktrees Part 4A. Les réponses de création réussie de worktree, ainsi que les réponses de restauration dont l’enfant est soit déplacé pendant l’inactivité, soit signale déjà le cwd du worktree vérifié, portent les métadonnées worktree plus worktreeState: "persisted-v1". Une restauration héritée best-effort, ou une restauration froide dont l’invite de restauration a été déclenchée plutôt que mise en attente (suppressWorktreeContextRestore désactivé, donc la route a demandé au pont de ne pas différer) et qui signale donc une invite active sans cwd actuel, peut encore retourner worktree sans cette attestation. Les clients demandant l’isolation doivent pré-vérifier cette balise et vérifier chaque réponse ; l’objet worktree seul n’est pas une preuve durable de propriété.

session_worktree_reset_v1 signifie que le démon prend en charge le transfert de propriété des worktrees : POST /session/:id/worktree-reset déplace la propriété du checkout d’une session de worktree persistée vers une nouvelle session de remplacement. Les réponses de restauration gagnent trois classifications 409 typées avec cela : worktree_session_superseded (le sidecar de la session porte un lien supersededBy — la classification est décidée uniquement à partir de ce lien, avant toute lecture de marqueur, et le lien est écrit avant que le marqueur ne bascule, donc le replacementSessionId du corps est une redirection à vérifier plutôt qu’une preuve de propriété : dans un état interrompu pré-commit, il nomme une session qui n’est pas le propriétaire du marqueur, ne peut pas elle-même être restaurée, et est récupérée par la réinitialisation réessayée), worktree_marker_missing (le marqueur de checkout est absent ; réinitialisez la tâche pour le recréer — une tentative de restauration ne peut pas le faire, car aucun chemin de restauration n’écrit de marqueur), et worktree_reset_interrupted (un transfert précédent a planté en cours de vol avec ses liens sidecar concordants ; réessayez la réinitialisation). La classification interrompue est vérifiée en premier : un marqueur manquant dont les liens supersedes/supersededBy concordent apparaît comme worktree_reset_interrupted, jamais comme worktree_marker_missing. Voir la section des routes ci-dessous pour le protocole de transfert et la taxonomie des échecs.

Les balises de fonctionnalité d’espace de travail et workspaces[] sont dynamiques. Les clients qui ajoutent un espace de travail doivent récupérer /capabilities à nouveau après la fin de la mutation ; le démon ne diffuse pas les changements de capacités aux clients qui ont mis en cache une réponse précédente. Oublier la persistance ne décharge pas un environnement d’exécution actif, donc cet environnement reste annoncé jusqu’au redémarrage.

GET /brand

Le branding produit de Web Shell, pour les hôtes qui souhaitent personnaliser la marque de la coquille. Résolu à partir de ui.brand dans les portées de paramètres opérateur. Contrôlé par la balise de fonctionnalité web_shell_brand ; un démon sans la route répond 404.

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

Les deux champs sont optionnels, et {} est une réponse normale. Un champ absent signifie “utiliser la marque intégrée du client” — Web Shell affiche son propre nom et son logo intégré. Les clients ne doivent pas traiter un corps vide comme une erreur.

Le gestionnaire répond toujours par 200, même lorsque le logo configuré a été rejeté. Un fichier manquant, un lien symbolique, un fichier lié physiquement, un répertoire, un document non-SVG ou un contenu supérieur à 32 KiB produisent un corps sans logoDataUri, et la raison est écrite dans stderr du démon comme qwen serve: GET /brand: ui.brand.logoPath …. Un client ne peut donc pas distinguer « aucune marque configurée » de « le logo de l’opérateur a été refusé » ; le canal destiné à l’opérateur est le journal du démon. Un avertissement est plus doux qu’un rejet, et il y en a deux : une racine <svg> sans viewBox utilisable et sans width/height positif non-percentage (un viewBox malformé ou d’aire nulle compte comme inutilisable), que le navigateur peut afficher vide à la taille fixe de la barre latérale ; et une racine liée à un préfixe dont les éléments non préfixés manquent de liaison d’espace de noms par défaut, ce qui les rend invisibles. Le middleware devant le gestionnaire répond avant qu’il ne s’exécute — 401 lorsque l’authentification bearer est requise et absente, 429 lorsque le limiteur de débit optionnel est activé. Un démon en cours de vidange ne rejette pas cette route : le limiteur de débit est permissif pendant la vidange, donc le gestionnaire continue de répondre 200 jusqu’à ce que l’écouteur se ferme et que le client voie une échec de connexion à la place. Le démarrage n’est pas un 503 sur cette route : sur le chemin par défaut de runtime différé, la requête est retenue jusqu’à ce que le runtime soit prêt puis répond 200, donc c’est un court délai d’expiration client qui peut se déclencher tôt. Un 503 avec code: "daemon_runtime_starting" atteint cette route uniquement sur les configurations qui répondent avant que le runtime soit prêt (par ex. --open) et est réessayable ; un 503 avec code: "daemon_runtime_failed" est terminal jusqu’au redémarrage du démon et ne porte pas de Retry-After — ne le réessayez pas.

Les paramètres de l’espace de travail ne contribuent jamais. La route charge les paramètres avec skipWorkspaceSettings, donc le .qwen/settings.json d’un dépôt ne peut pas renommer le produit ni nommer un fichier pour que le démon le lise et l’intègre en ligne dans chaque navigateur connecté. Seuls System Defaults, User et System sont lus, dans cet ordre de priorité. Pour la même raison, une valeur de marque est refusée avec un avertissement sur stderr du démon chaque fois que la substitution de placeholder la modifierait : la substitution puise dans l’environnement global au processus, que le bloc .qwen/.env ou env d’un espace de travail remplit en premier au démarrage. Un placeholder non résolvable (la variable n’est pas définie) est conservé verbatim, donc une variable mal orthographiée apparaît comme texte littéral plutôt que de basculer silencieusement vers une valeur par défaut.

logoDataUri doit être rendu comme une image, jamais injecté comme balisage. Le démon ne nettoie pas le SVG qu’il lit. Le SVG chargé via un src img ou un href de favicon ne peut pas exécuter de script ; le SVG injecté dans le document le peut. Web Shell ne l’assigne jamais qu’à un contexte d’image, et c’est cette invariance qui rend l’absence d’un assainisseur sûre.

Global au processus. La route ne prend aucun sélecteur d’espace de travail ni id de session : la valeur dérive de la configuration globale utilisateur, donc elle est identique pour chaque espace de travail servi par le démon. Elle est enregistrée après bearerAuth et le limiteur de débit, et avant le repli SPA de Web Shell, donc elle répond en JSON pour tout en-tête Accept.

POST /workspaces

Enregistrer un runtime d’espace de travail supplémentaire. Le chemin doit être un répertoire absolu existant, accessible, qui ne duplique ni n’imbrigue un autre espace de travail enregistré. L’enregistrement est local au processus sauf si le client envoie persist: true ; les clients doivent pré-voler persistent_workspace_registration avant de demander la persistance. Lorsque workspace_display_name est annoncé, la requête peut également inclure un displayName optionnel.

Lorsque git_workspace_clone est annoncé, la même route accepte également { "kind": "git", "url": "...", "target": "/absolute/new/path" }. Cette forme exige un target absolu qui n’existe pas encore, démarre un clone asynchrone, n’enregistre rien, et retourne 202 { "kind": "git-workspace-clone", "jobId": "..." }. Les réponses 201 et 200 ci-dessous décrivent les formes synchrones cwd et scratch ; la forme git n’enregistre rien, et la progression et l’annulation du clone utilisent GET/DELETE /workspace-git-clone-jobs/:jobId.

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

Un runtime nouvellement créé retourne 201 ; promouvoir un espace de travail secondaire déjà actif en persistant retourne 200. Le succès persistant inclut persisted: true :

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

displayName doit être une chaîne de moins de 256 caractères après suppression des espaces blancs environnants. Un résultat vide est traité comme pas de nom, et les caractères de contrôle C0 internes (U+0000–U+001F) ou DEL (U+007F) sont rejetés. Le null JSON n’est pas une valeur de création et retourne 400 invalid_display_name ; omettez le champ pour fournir aucun nom initial. Les noms d’affichage en double sont autorisés. Un nom fourni avec un enregistrement local au processus dure seulement pour ce processus démon ; persist: true le stocke avec l’enregistrement persistant afin qu’il puisse être restauré après redémarrage. Répéter la requête pour un espace de travail déjà persistant est idempotent et ne le renomme pas.

Les erreurs incluent 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, et 501 persistence_not_available / not_implemented.

PATCH /workspaces/:workspace

Mettre à jour une ressource d’espace de travail active sélectionnée par ID d’espace de travail ou cwd absolu encodé URL. Le point de terminaison ne supporte actuellement que les métadonnées de nom d’affichage :

{ "displayName": "Payments Production" }

Envoyez { "displayName": null } pour effacer le nom. Ici null est un sentinel de suppression mise-à-jour-seulement ; les valeurs non-null suivent les mêmes règles de normalisation de chaîne que POST /workspaces. La réponse est la projection d’espace de travail { id, cwd, displayName?, primary, trusted, removable? } mise à jour. Les métadonnées de runtime sont toujours mises à jour. Si le runtime a des identités d’enregistrement persistant correspondantes, chaque alias est mis à jour atomiquement via le magasin d’enregistrement schema-v1 existant ; le point de terminaison ne crée ni ne promeut jamais un enregistrement persistant.

Les champs non supportés échouent fermés plutôt que d’être ignorés silencieusement. Les erreurs incluent 400 empty_patch / invalid_display_name / unsupported_field / workspace_mismatch, 409 workspace_registration_in_progress, 500 workspace_registration_store_error, et 503 daemon_shutting_down.

DELETE /workspaces/:workspace

Supprimer un runtime secondaire amovible unique. Le sélecteur suit les règles de routage d’espace de travail pluriel et accepte soit un ID d’espace de travail soit un cwd absolu encodé URL. Le corps JSON optionnel est { "force": boolean } ; l’omettre demande une suppression non-force.

La suppression non-force retourne 409 workspace_busy avec un instantané activity lorsque le runtime gelé a des sessions, prompts, démarrages en attente, connexions ACP, tâches mémoire, ou workers de canal d’espace de travail. Envoyer { "force": true } demande la terminaison de ces ressources. La suppression de persistance est le point de commit : le nettoyage ultérieur est borné et best-effort, les échecs de nettoyage sont journalisés, et la suppression logique converge quand même au lieu de restaurer le runtime. Une réponse réussie est :

{
  "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
  }
}

Une requête non-force immédiatement occupée retourne un instantané d’activité rapide pré-vidange. Une fois la vidange démarrée, la réponse occupée ou réussie contient l’instantané final pris après la fermeture des portes d’admission et de vidange ACP et avant le début du nettoyage. Les erreurs incluent 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, et 503 daemon_shutting_down.

GET /workspace-registrations

Listez l’ensemble d’espaces de travail souhaités persistés pour cet espace de travail principal. Les entrées restent visibles avec active: false lorsqu’un répertoire stocké n’a pas pu être restauré lors du démarrage actuel. Une entrée reste active: true tant que son runtime se draine car le runtime possède encore des ressources actives jusqu’à la fin de la suppression. Les entrées incluent displayName optionnel lorsque l’enregistrement persistant en possède un.

{
  "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
    }
  ]
}

Renvoie 501 persistence_not_available lorsqu’aucun magasin d’enregistrements n’est configuré et 500 workspace_registration_store_error lorsque le magasin ne peut pas être lu.

DELETE /workspace-registrations/:id

Oublie un enregistrement persisté. Cela ne décharge pas un runtime actif ni ne termine ses sessions ; restartRequired: true signifie que le runtime actif disparaît au prochain redémarrage du démon.

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

Renvoie 404 workspace_registration_not_found, 500 workspace_registration_store_error ou 501 persistence_not_available. Comme les autres routes de mutation, ce point de terminaison nécessite une authentification de mutation lorsque l’authentification du démon est activée.

Routes d’état du runtime en lecture seule

Ces routes rapportent des instantanés de runtime côté démon. Ce sont des routes v1 additives, elles ne modifient pas l’état et ne changent pas la version du protocole serve. Les routes de statut d’espace de travail ne démarrent intentionnellement pas le processus enfant ACP simplement parce qu’un client interroge une route GET. GET /workspace/mcp renvoie initialized: false avec un instantané vide lorsque le démon est inactif et ne conserve aucune observation MCP ; si un enfant actif a répondu plus tôt, la lecture inactive rejoue cette observation avec source: "cache" et sa valeur initialized originale. GET /workspace/skills sert plutôt une observation de démon conservée ou une énumération locale au démon, et signale initialized: false avec une entrée errors (indisponibilité retentable, pas un catalogue vide) uniquement lorsqu’aucune observation conservée n’existe et que les deux sources sont indisponibles (ou qu’une lecture froide est limitée) — voir GET /workspace/skills. GET /workspace/providers est répondu localement au démon à partir des paramètres d’espace de travail et de l’environnement, il ne dépend donc pas d’un enfant ACP actif, et acpChannelLive signale la vivacité. Son initialized est true sur le chemin de succès et false avec une entrée errors lorsque les paramètres d’espace de travail ou la configuration du modèle ne peuvent pas être résolus ; les démons construits sans constructeur de fournisseur local au démon reviennent à l’instantané ACP actif, et la réponse locale au démon omet les modèles enregistrés au runtime. Les routes de statut de session nécessitent une session active et renvoient 404 { code: "session_not_found", ... } pour les IDs inconnus.

Balises de capacité :

• 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
• Les entrées de moniteur de session_monitor_tool_correlation provenant de GET /session/:id/tasks incluent toolUseId pour la corrélation transcript-tâche
• session_status → GET /session/:id/status
• session_info → GET /workspace/:id/session-info et 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} et GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId

workspace_acp_status signale la vivacité ponctuelle du canal ACP de l’espace de travail principal comme { channelLive: boolean }. Le gestionnaire ne crée pas de canal, mais atteindre une route de runtime peut d’abord démarrer un runtime de démon différé, dont la politique de démarrage configurée peut préchauffer indépendamment ACP. L’instantané n’est pas un bail : les clients doivent laisser la création de Session revalider ou démarrer le canal.

Préchauffage ACP

Balise de capacité : workspace_acp_preheat.

POST /workspace/acp/preheat?timeoutMs=N initialise au mieux (best-effort) le canal ACP de l’espace de travail principal. timeoutMs vaut 5000 par défaut et doit être un entier positif inférieur ou égal à 60000. Les appelants concurrents et la création de Session partagent la même initialisation de pont. Un délai d’expiration de requête termine uniquement cette attente HTTP ; il n’annule pas l’initialisation partagée.

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

ready est toujours égal à channelLive. Une réponse en direct omet reason et error ; sinon, reason est soit timeout, soit error. durationMs mesure l’appel HTTP actuel, et non la durée de vie complète d’une initialisation à laquelle l’appel s’est joint. Un délai opérationnel ou un échec renvoie HTTP 200. Un timeoutMs invalide renvoie 400, tandis que les échecs d’authentification, de limitation de débit et d’exécution différée conservent leurs réponses normales.

Les deux routes ACP workspace sont au singulier et concernent uniquement le workspace principal. Les clients ne doivent pas les utiliser pour un workspace secondaire ni interpréter l’une des réponses comme une garantie durable de disponibilité.

Cellule d’état commune :

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 est une énumération fermée partagée par /workspace/preflight, /workspace/env et (éventuellement) les garde-fous MCP afin que les clients SDK puissent afficher les remédiations par catégorie plutôt que d’analyser des messages libres. Les sept littéraux de statut originaux provenaient de #4175 ; restore_timeout a été ajouté séparément pour les demandes de restauration de session. blocked_egress reste réservé jusqu’à ce que la sonde egress soit implémentée.

Les charges utiles de statut n’exposent jamais les valeurs d’environnement MCP, les en-têtes, les détails OAuth/compte de service, les clés API du fournisseur, les baseUrl / envKey du fournisseur, le corps de la compétence, les chemins système de fichiers de la compétence, les définitions de hook ou les valeurs des variables d’environnement secrètes. /workspace/env signale uniquement la présence des variables d’environnement sur liste blanche ; les URL de proxy sont dépouillées de leurs identifiants et réduites à host:port avant transmission.

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 est l’un de not_started, in_progress ou completed. transport est l’un de stdio, sse, http, websocket, sdk ou unknown. errors est omis lorsque la découverte réussit.

source est "live" tant que l’enfant ayant produit l’observation est actif. Lorsque le démon est inactif et qu’un enfant actif a répondu plus tôt, la réponse rejoue cette observation avec source: "cache" et les valeurs originales de l’enfant, y compris initialized: true et sa liste de serveurs. L’observation mise en cache est effacée uniquement lorsqu’une nouvelle découverte MCP commence ; la suppression de l’enfant ne la supprime pas, donc un GET /workspace/mcp inactif peut signaler un catalogue qu’aucun enfant actif ne sert actuellement.

Garde-fous du client MCP (problème #4175 ). Les démons actuels étendent la charge utile avec quatre champs additifs et une cellule de budget portée par la capacité :

{
  "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 est l’un des éléments enforce, warn ou off. clientBudget est absent si aucun budget n’a été défini. budgets[] est toujours un tableau sur les démons annonçant mcp_guardrails (éventuellement vide lorsque budgetMode === 'off') ; les anciens démons omettent entièrement ce champ. Lorsque mcp_workspace_pool est annoncé, la cellule contient scope: 'workspace' et couvre le pool partagé de l’exécution d’espace de travail sélectionnée. Lorsque cette balise est absente, y compris sous QWEN_SERVE_NO_MCP_POOL=1, le gestionnaire hérité émet scope: 'session'. Les consommateurs DOIVENT tolérer des valeurs de portée supplémentaires non reconnues.

disabledReason sur les cellules par serveur distingue désactivé par l’opérateur ('config' — liste de configuration disabledMcpServers) de refusé pour cause de budget ('budget' — découvert mais jamais connecté en raison du mode enforce). Les refus sont déterministes selon l’ordre de déclaration Object.entries(mcpServers). Le champ status: 'error', errorKind: 'budget_exhausted' par serveur masque le champ brut mcpStatus: 'disconnected' (qui est vrai mais ne représente pas la sévérité visible par l’opérateur).

L’application du budget est pilotée par les capacités. Avec mcp_workspace_pool, les sessions au sein d’une même exécution d’espace de travail partagent les transports et un seul WorkspaceMcpBudget ; différentes exécutions d’espace de travail ne partagent jamais un pool ou un budget. Sans la balise, chaque McpClientManager de session ACP applique sa propre copie de la limite et l’instantané représente cette vue de session héritée.

Détection de la pression budgétaire. Deux surfaces, toutes deux peuplées après PR-14b :

• Événements push (annoncés via mcp_guardrail_events) : abonnez-vous à GET /session/:id/events et filtrez les trames mcp_budget_warning / mcp_child_refused_batch via KnownDaemonEvent. La machine à états se déclenche une fois lors du franchissement ascendant du seuil de 75 % (réarmée en dessous de 37,5 %) ; les refus sont regroupés une fois par passe de découverte en mode enforce.

• Sondage instantané (annoncé via mcp_guardrails) : GET /workspace/mcp et inspectez la cellule de budget (budgets[0]) ainsi que mcp_workspace_pool pour déterminer sa portée :

• budgets[0].status === 'warning' ⇔ liveCount >= 0.75 * clientBudget (correspond au seuil d’hystérésis utilisé par l’événement push de PR 14b).

• budgets[0].status === 'error' ⇔ refusedCount > 0 (un ou plusieurs serveurs ont été refusés lors de cette passe de découverte).

• budgets[0].status === 'ok' ⇔ inférieur au seuil de 75 % ET aucun refus.

Cadence de sondage recommandée : alignée sur tout ce qui sonde déjà /workspace/mcp ; l’instantané est peu coûteux et la cellule de budget n’entraîne aucun coût de découverte supplémentaire. Les clients SDK qui s’abonnent aux événements push bénéficient toujours de l’instantané pour l’état après une déconnexion prolongée (la profondeur de l’anneau de rejeu SSE est finie — --event-ring-size, défaut 8000 — donc un client hors ligne plus longtemps que la couverture de l’anneau revient à une resynchronisation par instantané).

GET /workspace/skills

Les routes d’inventaire principale et qualifiée par workspace renvoient immédiatement un instantané conservé tout en revalidant en arrière-plan. Les démarrages sont limités à une fois par seconde, mesurés depuis le début de la tâche, et les lecteurs concurrents partagent une tâche. La revalidation en arrière-plan libère son créneau après cinq secondes ; le délai permet une nouvelle tentative mais n’annule pas l’observation ni le travail ACP. Les lectures froides respectent le délai de demande configuré d’ACP (dix secondes par défaut), puis l’énumération locale au démon si ACP est indisponible. Elles n’imposent pas le délai d’arrière-plan à l’une ou l’autre source. Une lecture froide qui échoue dans la seconde suivant son début laisse le reste de cette fenêtre renvoyer immédiatement un statut indisponible ; les échecs plus lents ne laissent aucune fenêtre de limitation, donc les clients ont besoin de leur propre backoff de nouvelle tentative. Une observation réussie tardive en arrière-plan peut publier pendant qu’une nouvelle tentative est en attente, mais ne peut pas remplacer une observation commencée plus tard qui a déjà publié. Les tâches invalidées ne peuvent pas publier ; une observation réussie invalidée peut encore répondre à son appelant original. L’invalidation explicite supprime l’inventaire connu comme invalide et efface la limitation. Un préchauffage ACP réussi qui se termine avant son délai invalide également l’inventaire conservé, y compris lorsque l’enfant était déjà actif, afin que la lecture suivante voie l’enfant. Un préchauffage qui dépasse le délai puis trouve le canal actif signale également ready: true — prêt est toujours égal à channelLive — mais conserve l’inventaire conservé car le démarrage peut être incomplet ; la lecture suivante renvoie ces données conservées, et la revalidation en arrière-plan les remplace dès que la limitation de démarrage d’une seconde le permet. La suppression de compétence contourne l’instantané et la limitation mais nécessite un catalogue fraîchement énuméré : elle utilise le repli local et ne répond jamais à partir d’un instantané conservé. Les lectures d’identité d’activation contournent l’instantané et la limitation, attendant une nouvelle observation avec repli local puis l’instantané conservé lorsque les deux sources échouent.

Les réponses d’inventaire portant une observation conservée du démon incluent en outre des métadonnées d’instantané facultatives. Les lectures directes de statut de configuration/exécution, les inventaires de ressources de session et les démons plus anciens les omettent. Une lecture froide réussie obsolète renvoie un instantané conservé plus récent si disponible ; sinon, elle renvoie sa propre observation non mise en cache sans ces métadonnées. Seules les observations initialisées sans erreurs peuvent remplacer l’instantané conservé :

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

observedAt est l’heure de début en millisecondes Unix de l’observation réussie ; ageMs est recalculé à chaque réponse, incluant de manière conservatrice le temps de collecte. stale signifie que l’observation a au moins une seconde d’ancienneté. refreshing indique si une revalidation occupe le créneau partagé ; les observations ayant expiré peuvent encore se terminer après la libération du créneau. Les lectures échouées, les expirations de créneau et les relectures après l’arrêt de l’environnement d’exécution ne renouvellent pas l’horodatage ; une publication réussie ultérieure enregistre sa propre heure de début d’observation. Les clients peuvent afficher cette ancienneté, mais il ne s’agit ni d’une révision du système de fichiers ni d’une preuve que toutes les sessions sont à jour. Si aucun instantané initialisé n’existe et que les deux sources sont indisponibles (ou que la lecture à froid est limitée), la réponse contient initialized: false, une entrée errors, et aucune métadonnée snapshot. Il s’agit d’une indisponibilité réessayable, et non d’un catalogue vide ; un catalogue vide valide possède initialized: true. Les lectures de statut n’invoquent pas de commandes d’actualisation des Skills affectant les sessions. Les environnements d’exécution d’espace de travail fermés ou en cours de vidange rejettent les lectures ; les données conservées survivent au ramassage des canaux enfants, mais pas à la mise à la retraite de l’environnement d’exécution.

{
  "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 est l’une des valeurs project, user, extension ou bundled. userInvocable (booléen, facultatif) est omis pour les skills normales (signifiant true) et n’est présent sous forme de false que lorsque le skill ne peut pas être invoqué manuellement. Il ne contrôle pas les routes de bascule Skill uniquement paramétrables décrites ci-dessous. modelInvocable est indépendant : false signifie que le skill reste disponible manuellement mais est masqué pour l’invocation par le modèle. installedPath est le chemin absolu existant vers le SKILL.md du skill ; le démon le renvoie tel qu’il est stocké sans résoudre séparément les liens symboliques ni le normaliser. Les démons actuels l’émettent pour chaque skill, tandis que les clients doivent tolérer son absence dans les anciens démons v1. Le corps des skills, les hooks, skillRoot et autres configurations de skill restent exclus. errors est omis lorsque la découverte réussit.

Pour les skills appartenant à une extension, extensionName est le nom canonique du manifeste et peut être utilisé en toute sécurité comme identité du propriétaire. extensionDisplayName est une valeur de présentation localisée facultative et peut ne pas être unique. Les nouveaux clients doivent afficher extensionDisplayName ?? extensionName ; les anciens démons omettent le champ d’affichage.

Les lectures répétées sont servies à partir du dernier instantané d’espace de travail validé, périodiquement revalidé par rapport au cache en mémoire de l’enfant. Les lectures en régime permanent ne scannent pas les répertoires de skills ni ne réanalysent les fichiers SKILL.md ; le repli local à froid du démon peut énumérer depuis le disque. L’enfant vérifie bien que ses sources d’extensions sont inchangées — un readdir du répertoire des extensions ainsi qu’un stat par entrée, le fichier d’activation et l’état d’activation du magasin — et actualise uniquement lorsqu’ils ont changé, afin qu’une extension installée ou activée/désactivée hors du démon soit détectée par la revalidation et apparaisse lors d’une lecture ultérieure après la publication de cette revalidation. Une lecture chaude renvoie toujours l’observation conservée, même lorsqu’elle démarre un travail en arrière-plan. Les modes sûr et nu sautent la vérification, correspondant à leur exclusion des extensions.

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
        }
      ]
    }
  ]
}

Les modèles sont regroupés par type d’authentification. Les diagnostics de connexion aux fournisseurs résident dans la cellule providers de /workspace/preflight ; le préflight de l’environnement réside dans /workspace/preflight et /workspace/env (ci-dessous). errors est omis lorsque la construction de l’instantané réussit.

GET /workspace/env

Signale l’environnement d’exécution, la plateforme, le bac à sable, le proxy du processus du démon, ainsi que la présence de variables d’environnement secrètes sur liste blanche. Répond toujours à partir de l’état process.* — le démon ne lance jamais d’enfant ACP pour servir cette route, et la réponse est identique que ACP soit actif ou inactif. Le champ acpChannelLive est purement informatif.

{
  "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
    }
  ]
}

Forme de la cellule :

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;
}

Politique de caviardage. Les cellules kind: 'env_var' n’incluent jamais un champ value ; les clients voient uniquement present: boolean. Les cellules kind: 'proxy' font passer la valeur brute de l’environnement à travers le caviardage des identifiants (redactProxyCredentials) puis à travers l’analyse URL afin que la ligne ne transporte que host:port. NO_PROXY est transmis verbatim à travers le caviardage car il s’agit d’une liste d’hôtes plutôt que d’une URL. La liste blanche des variables d’environnement secrètes énumérées comprend actuellement OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, DASHSCOPE_API_KEY, OPENROUTER_API_KEY et QWEN_SERVER_TOKEN. Les autres variables d’environnement ne sont pas énumérées, de sorte que les secrets définis accidentellement restent invisibles.

GET /workspace/preflight

Signale les contrôles de préparation du démon. Les cellules au niveau du démon (node_version, cli_entry, workspace_dir, ripgrep, git, npm) sont toujours peuplées à partir de process.* et node:fs. Les cellules au niveau ACP (auth, mcp_discovery, skills, providers, tool_registry, egress) nécessitent un enfant ACP actif — lorsque le démon est inactif, elles émettent des espaces réservés status: 'not_started'. La route ne lance jamais ACP uniquement pour peupler les cellules ; les cellules correspondantes reviennent à not_started.

Réponse inactive (pas d’enfant ACP) :

{
  "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)"
    }
  ]
}

Forme de la cellule :

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>;
}

Sémantique de errorKind :

• missing_binary — Version Node inférieure à celle requise, QWEN_CLI_ENTRY manquant, ripgrep / git / npm absents du PATH (avertissements plutôt qu’erreurs pour les binaires facultatifs).
• missing_file — boundWorkspace n’existe pas ou n’est pas un répertoire ; erreur d’analyse de skill pointant vers un fichier manquant ou illisible.
• parse_error — échec d’analyse de SKILL.md, configuration JSON malformée.
• auth_env_error — validateAuthMethod a renvoyé une chaîne d’échec non nulle, ou une sous-classe ModelConfigError propagée depuis la résolution du fournisseur.
• init_timeout — Rejet withTimeout dans le pont (un délai réel dépassé en attendant un aller-retour ACP). Reconnu via la classe typée BridgeTimeoutError. Note : une cellule transitoire mcp_discovery warning avec connecting > 0 ne porte PAS ce type — il s’agit d’un état normal de poignée de main en cours, distinct d’un véritable dépassement de délai.
• restore_timeout — un chargement ou une reprise de session a dépassé le budget de restauration dédié. La réponse REST est 504 et peut être répétée ; elle se distingue de l’initialisation des processus enfants et des limites bornées de la fenêtre de relecture.
• protocol_error — ACP extMethod rejeté car le canal s’est fermé en cours de requête, ou parce que le registre d’outils était inattendu absent.
• blocked_egress — réservé pour PR 14 (#4175). PR 13 laisse la cellule egress comme status: 'not_started'.

Si le pont échoue à atteindre le processus enfant ACP lors du traitement d’une requête préliminaire (par exemple, une fermeture de canal en cours de requête), le tableau errors de l’enveloppe contient un seul élément ServeStatusCell décrivant l’échec et les cellules reviennent aux espaces réservés ACP not_started. Les cellules au niveau du démon sont toujours renvoyées.

GET /workspace/tools

Renvoie le catalogue d’outils signalé par le processus enfant ACP de l’espace de travail principal. Il s’agit d’une route héritée pour l’espace de travail principal : elle n’a pas de sélecteur d’espace de travail et ne doit pas être utilisée pour déduire les outils d’un environnement d’exécution non principal.

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

Lorsqu’aucun processus enfant ACP n’est actif, la route renvoie toujours 200 avec acpChannelLive: false, un tableau tools vide, et une entrée not_started dans le tableau optionnel errors. Les échecs inattendus du pont utilisent la réponse d’erreur standard 500 du pont. La méthode SDK TypeScript est workspaceTools() ; il n’y a pas de balise de capacité dédiée, donc les clients prenant en charge les anciens démons doivent traiter 404 comme non pris en charge.

Routes de fichiers d’espace de travail

Les routes de fichiers héritées résolvent les chemins via l’espace de travail principal ; les routes /workspaces/:workspace/... résolvent les chemins via l’espace de travail de l’environnement d’exécution sélectionné. Les réponses utilisent des chemins relatifs à l’espace de travail et ne renvoient jamais de chemins absolus du système de fichiers pour les cas de succès normaux. Les réponses de fichiers réussies incluent :

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

Les erreurs de système de fichiers utilisent cette forme JSON :

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

Les valeurs errorKind incluent 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, et ambiguous_text_match.

GET /file

Lit un fichier texte. Paramètres de requête : path (requis), maxBytes, line, limit, et cursor. Le démon rejette les fichiers binaires. Les fichiers dépassant la limite de capture complète de 256 KiB nécessitent au moins un argument de fenêtre explicite (line, limit, ou maxBytes) ; une requête sans aucun d’entre eux reste file_too_large. Une telle fenêtre est diffusée en flux, et son contenu UTF-8 renvoyé reste plafonné à 256 KiB. maxBytes s’applique toujours aux octets de réponse UTF-8 après décodage, y compris lorsque la source utilise un autre encodage pris en charge dans la limite de capture complète.

Les décalages de ligne sont résolus en parcourant depuis le début du fichier, donc une fenêtre est également refusée avec file_too_large si l’atteindre impliquerait de lire plus de 8 MiB (MAX_TEXT_SCAN_BYTES). Utilisez GET /file/bytes pour atteindre un décalage plus profond directement. Un grand texte dans un encodage que la route ne peut pas décoder renvoie binary_file, pas file_too_large — réessayer avec une fenêtre plus petite ne peut pas aider, et readBytes est le même remède qui s’applique déjà aux binaires.

Pour les fichiers dans la limite de capture complète, la réponse inclut hash, un digest SHA-256 sur les octets bruts sur disque pour tout le fichier, même si line, limit, ou maxBytes ont renvoyé une tranche. Les grandes fenêtres partielles omettent hash, conservent le complet sizeBytes, définissent truncated: true, et renvoient originalLineCount: null lorsque le flux s’arrête avant EOF.

Pagination avec cursor

Nécessite la capacité workspace_file_read_cursor. Une réponse ayant plus à donner renvoie hasMore: true et, lorsqu’un décalage d’octet de fichier est dérivable, un jeton nextCursor. Le renvoyer comme cursor reprend en O(1), où un décalage line profond coûte une analyse depuis l’octet 0 et est refusé au-delà de 8 MiB.

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

cursor et line sont mutuellement exclusifs (parse_error) — tous deux désignent un point de départ. Un curseur mal formé ou trop long est parse_error ; un curseur dont le fichier a été remplacé ou tronqué est hash_mismatch (409). L’ajout de données n’invalide pas un curseur en cours, ce qui est précisément le cas d’usage pour lequel cette fonctionnalité existe.

content omet le saut de ligne final de sa dernière ligne, comme toute autre lecture, donc un client réassemblant les pages les joint avec \n. hasMore n’est pas une reformulation de nextCursor : un petit fichier non-UTF-8 lu avec un limit a plus de contenu mais pas de décalage d’octet dérivable, donc il signale hasMore: true avec nextCursor: null. Le curseur est également nul lorsque la limite d’octets coupe la ligne actuelle, car reprendre depuis ce décalage renverrait une ligne partielle. Pour beaucoup de lignes courtes, abaissez limit jusqu’à ce que la page se termine avant la limite d’octets et renvoie un curseur. Pour une seule ligne surdimensionnée, demandez explicitement la ligne suivante (par exemple, line=2 en commençant à la ligne 1), puis continuez avec des curseurs ; utilisez GET /file/bytes lorsque la ligne surdimensionnée complète est requise.

{
  "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

Lit les octets bruts d’un fichier sans décodage. Paramètres de requête : path (requis), offset (défaut 0), et maxBytes (défaut 65536, max 262144). Cette route prend en charge les fenêtres bornées sur de gros fichiers binaires sans charger tout le fichier. La réponse inclut hash uniquement lorsque la fenêtre renvoyée couvre l’intégralité du fichier.

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

GET /stat

Renvoie les métadonnées pour un chemin de l’espace de travail principal. Le paramètre de requête path est requis.

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

type est file, directory, symlink, ou other. La route utilise la frontière de fichier de l’espace de travail et l’enveloppe d’erreur système de fichiers commune décrite ci-dessus. La méthode SDK TypeScript est fileStat().

GET /list

Liste un répertoire de l’espace de travail principal. Le paramètre de requête path est obligatoire ; includeIgnored=1 (ou true) inclut les entrées correspondant aux règles d’ignorance. La réponse est limitée à 2 000 entrées et définit truncated: true lorsqu’il y en a davantage.

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

Le champ kind de chaque entrée est file, directory, symlink ou other. La méthode du SDK TypeScript est dirList().

GET /glob

Correspond aux chemins dans l’espace de travail principal. Le paramètre de requête pattern est obligatoire. L’option cwd restreint la recherche, includeIgnored=1 (ou true) inclut les chemins ignorés, et maxResults est un entier compris entre 1 et 50 000 (par défaut 5 000).

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

Les correspondances sont relatives à l’espace de travail. Les valeurs de requête invalides renvoient 400 ; la confiance dans l’espace de travail, le confinement, les chemins manquants et les échecs inattendus utilisent l’enveloppe d’erreur système de fichiers commune. La méthode du SDK TypeScript est glob().

POST /file/write

Crée ou remplace un fichier texte. Il s’agit d’une route de mutation stricte : une demande principale sans jeton via boucle locale fiable est autorisée. Une demande principale sans jeton qui atteint la porte sans autorité de boucle locale fiable renvoie 401 { "code": "token_required" }. Les échecs d’authentification par jeton configuré et par identifiants Local Control sont rejetés plus tôt avec un simple 401 Unauthorized ; avec --require-auth, le middleware porteur global rejette les demandes non authentifiées avant que la route ne s’exécute.

Corps :

{
  "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 doit être create ou replace. create ne remplace jamais un fichier existant (409 file_already_exists). replace nécessite expectedHash ; les hachages manquants ou malformés sont 400 parse_error, et les hachages obsolètes sont 409 hash_mismatch. expectedHash est sha256: suivi de 64 caractères hexadécimaux minuscules, calculés sur les octets bruts sur disque.

bom, encoding et lineEnding peuvent être fournis. Le remplacement conserve par défaut le profil d’encodage du fichier existant ; les champs explicites le remplacent. Les écritures binaires sont hors du périmètre.

Le démon écrit dans un fichier temporaire aléatoire dans le répertoire cible, effectue fsync là où c’est pris en charge, revérifie le hachage actuel immédiatement avant rename(), puis renomme pour mettre en place. Cela empêche l’observation de fichiers partiels et sérialise les écritures initiées par le démon vers le même fichier, mais ce n’est pas une comparaison-échange atomique inter-processus au niveau du noyau : un éditeur externe peut encore entrer en concurrence dans la petite fenêtre entre la vérification finale du hachage et le renommage.

{
  "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

Applique une seule substitution textuelle exacte dans un fichier texte existant. Il s’agit également d’une route de mutation stricte et nécessite expectedHash.

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

oldText doit être non vide et se produire exactement une fois. Aucune correspondance renvoie 422 text_not_found ; plusieurs correspondances renvoient 422 ambiguous_text_match. La route préserve l’encodage, le BOM et les fins de ligne, et revérifie expectedHash immédiatement avant le renommage atomique.

Les écritures/modifications explicites sur des chemins ignorés sont autorisées car l’appelant authentifié a nommé le chemin. Les réponses de succès et les événements d’audit incluent 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

Nécessite workspace_qualified_rest_core et workspace_directory_create, une autorité de mutation stricte et un espace de travail local actif fiable. Corps :

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

Le parent doit exister. La création est exclusive : un fichier ou répertoire existant renvoie 409 file_already_exists ; un lien symbolique final renvoie 400 symlink_escape. Le succès est 201 { "kind": "directory_create", "path": "src/new-folder" }. La méthode SDK est WorkspaceDaemonClient.createWorkspaceDirectory(path, clientId?).

POST /workspaces/:workspace/directory/delete

Nécessite workspace_qualified_rest_core et workspace_directory_delete sous la même politique stricte de mutation et d’exécution locale fiable. Corps :

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

Supprime récursivement un répertoire vide ou non vide. Les racines d’espace de travail, les fichiers réguliers et les liens symboliques finaux sont rejetés ; les entrées de liens symboliques imbriqués sont supprimées sans suivre leurs cibles. Une cible manquante renvoie 404 path_not_found. Le succès est 200 { "kind": "directory_delete", "path": "src/old-folder" }. La méthode SDK est WorkspaceDaemonClient.deleteWorkspaceDirectory(path, clientId?).

Les deux routes de répertoire préservent le nom final lexical tout en résolvant son parent dans l’espace de travail sélectionné. Les chemins ne doivent pas se terminer par un séparateur ; les motifs de chemin suspects renvoient 400 path_outside_workspace, tandis que les formes de feuille malformées renvoient 400 parse_error. Les fabriques personnalisées non prises en charge renvoient 422 ; les espaces de travail SSH sont rejetés par la frontière SSH avec 501. Les propriétaires inconnus, indisponibles, supprimés ou non fiables ne retombent jamais sur le principal.

La suppression est permanente et les échecs peuvent laisser une suppression partielle. Un écrivain concurrent peut causer ENOTEMPTY, renvoyé comme 503 io_error ; réessayez la même opération après l’arrêt de l’écrivain. Les verrous par chemin ne sérialisent pas un répertoire contre chaque écriture enfant, et le remplacement de répertoire externe ne peut pas être rendu atomique par des vérifications portables basées sur le chemin. Les mutations explicites de répertoires ignorés sont autorisées et les événements d’audit annotent matchedIgnore lorsque applicable ; la création enregistre sizeBytes: 0.

GET /session/:id/context

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

Pour une session de premier niveau, state reflète les mêmes formes d’options de modèle/mode/config ACP utilisées par POST /session, POST /session/:id/load et POST /session/:id/resume. Un identifiant de session virtuelle préfixé par subagent. se résout par rapport à son runtime parent et renvoie un objet state vide.

GET /session/:id/supported-commands

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

availableCommands est le même instantané de commande utilisé par la notification SSE available_commands_update. availableSkills liste uniquement les noms de compétences ; les clients ne doivent pas s’attendre à des corps ou des chemins de compétences via cette route.

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
    }
  ]
}

Cette route est un instantané hors bande en lecture seule. Elle n’est intentionnellement pas une invite et peut être interrogée pendant que la session diffuse. La réponse ne contient que des métadonnées sur liste blanche provenant des registres de tâches agent, shell et moniteur ; les contrôleurs, minuteurs, décalages, messages en attente et objets de registre bruts ne sont jamais exposés.

Les tâches d’agent engendrées par un autre sous-agent (sous-agents imbriqués, limités par maxSubagentDepth) comportent trois champs de lignée facultatifs : parentAgentId (le id de la tâche d’agent qui a engendré), parentName (le subagentType de l’agent qui a engendré, capturé lors de l’enregistrement afin de survivre à l’éviction du parent du registre), et depth (profondeur de lancement à base 0 ; 0 = engendré par la session de niveau supérieur). Les agents lancés par la session de niveau supérieur omettent parentAgentId et parentName ; les clients doivent traiter ces trois champs comme facultatifs et revenir à une liste plate en leur absence.

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

Détail à la demande pour une tâche shell. GET /session/:id/tasks ne contient que des faits relatifs au cycle de vie ; cette route lit le fichier de sortie capturé et sonde l’arbre des processus, de sorte qu’un panneau de détail ouvert le demande séparément.

La méthode ACP est _qwen/session/task_runtime, avec les paramètres sessionId et taskId. Les deux transports résolvent le propriétaire de la session active ; ACP exige également que la connexion possède la session.

Le taskId du chemin est résolu par rapport au propre registre shell de la session ; les appelants ne passent jamais un chemin de fichier.

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

runtime est null lorsque la tâche est inconnue, a été évincée ou n’est pas une tâche shell. memoryBytes est l’ensemble résident de l’arbre des processus du shell, échantillonné uniquement pendant l’exécution de la tâche ; les pages partagées sont comptées une fois par processus, et un bac à sable conteneur peut n’exposer que le processus wrapper. outputTail est plafonné à la même limite de 8 KiB utilisée par la notification de fin, et outputTailTruncated marque une fin qui commence au milieu du fichier. outputError est défini lorsque le fichier ne peut pas être lu ; les champs d’une partie ayant réussi peuvent toujours être présents.

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

Contrôle une exécution de workflow, ou en démarre une nouvelle. La méthode ACP est _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" }
}

Ce que taskId nomme dépend de l’action :

args, sourceRef et script sont lus uniquement par run-saved et run-script. args est lié à la variable globale args du script et peut être n’importe quelle valeur JSON ; sourceRef est le propre {id, revision} de l’appelant, enregistré sur l’exécution, son journal et son instantané ; script est la source que run-script exécute et qui est requise par celui-ci. Une nouvelle tentative ou une réexécution rejoue le propre args et sourceRef de l’exécution originale — c’est ce qui fait qu’il s’agit de la même exécution — de sorte que ces champs sont ignorés ainsi que les actions de contrôle.

Une exécution démarrée appartient à la session : elle s’exécute en arrière-plan sans invite d’approbation, et sa fin atteint le canal de fin de la session. Elle constitue ensuite une cible retry/rerun comme toute autre exécution.

retry et rerun acceptent également une exécution restaurée depuis l’historique (isHistorical dans GET /session/:id/tasks), telle qu’une interrompue par un redémarrage du démon : l’exécution est relancée à partir du script, args et sourceRef de son instantané, et elle s’enregistre auprès de la session qui a envoyé l’action et lui signale sa fin. Un retry reprend le journal de l’exécution sous le même identifiant d’exécution et s’applique à une exécution failed pour laquelle aucun processus n’est encore en cours d’exécution ; un rerun démarre un nouvel identifiant d’exécution à partir de n’importe quelle exécution terminée. Une entrée d’historique portant argsOmitted a été lancée avec un args trop volumineux pour être conservé, de sorte qu’aucune action ne s’y applique. Il en va de même pour un instantané écrit avant que args ne soient conservés, qui ne porte ni argsOmitted ni argsRecorded : le journal d’une exécution est indexé à partir d’un hachage de son args, de sorte que relancer une exécution dont l’historique ne peut nommer le args ne rejouerait rien et rediffuserait chaque agent. Les deux refus sont workflow_args_unavailable, et GET /session/:id/tasks les signale tous deux comme argsUnavailable sur l’entrée, afin qu’un client puisse masquer les deux actions plutôt que de découvrir le refus en effectuant l’appel. argsOmitted reste à côté comme raison, pour un client souhaitant préciser laquelle. Les args eux-mêmes ne sont jamais transmis sur le réseau.

run-script ne transmet aucun nom de définition, de sorte que l’exécution est étiquetée par le propre export const meta du script — un script compilé devrait en déclarer un, sinon l’exécution n’affiche que son identifiant.

La réponse est {"changed": true, "status": "running", "taskId": "<runId>"} pour une exécution démarrée, {"changed": true, "status": "<status>"} pour une action de contrôle ayant pris effet, et {"changed": false} lorsqu’il ne s’est rien passé : Workflow est indisponible pour la session (désactivé, mode nu, dossier non fiable), l’espace de travail n’est pas fiable, le nom du workflow enregistré est inconnu, l’identifiant d’exécution est inconnu, ou un autre démarrage est déjà en cours sous le même taskId. Seuls les démarrages chevauchants sont dédupliqués : deux appels run-script concurrents sous un seul taskId démarrent une seule exécution. Une fois ce démarrage revenu, la clé est libérée ; la soumettre à nouveau peut démarrer une autre exécution, même si la première est toujours active. La clé ne fournit pas d’idempotence de nouvelle tentative après une réponse perdue.

Un paramètre rejeté est un 400 (-32602 via ACP), et non une exécution démarrée : un action inconnu, un run-script sans script, un sourceRef qui n’est pas un {id, revision} de chaînes non vides, ou un script rejeté avant le lancement en raison d’une syntaxe invalide ou d’une violation de déterminisme. Les erreurs d’entrée de démarrage de Workflow portent workflow_invalid_params et conservent le message de rejet.

Quatre refus proviennent de l’état stocké de l’exécution plutôt que de la requête. Chacun est -32602 via ACP, portant son errorKind et son data.httpStatus. Trois sont des 409 ; le quatrième, workflow_not_recorded, est un 503, car rien n’a été démarré et le même appel peut simplement être refait : un retry enregistre que l’exécution est de nouveau en cours avant de démarrer — cet enregistrement est ce qui empêche un autre processus de la démarrer une seconde fois — et l’enregistrement n’a pas pu être écrit.

workflowToolFeatures dans GET /session/:id/supported-commands annonce runSavedArgs et runScript ; un démon sans eux n’accepte ni l’entrée de démarrage ni l’action run-script. Il contient également nameOnly, vrai lorsque le modèle de la session ne peut exécuter que des workflows nommés (tools.workflowNameOnly) : les appels script et scriptPath du modèle lui-même sont refusés, tandis que toutes les actions ci-dessus, y compris run-script, démarrent toujours des exécutions. retryHistorical est vrai lorsque retry et rerun acceptent une exécution restaurée à partir de l’historique ; un ancien démon leur répond par {"changed": false}, donc un client ne doit proposer ces contrôles pour une entrée d’historique que si elle est signalée.

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"
    }
  ]
}