qwen serve HTTP-Protokollreferenz

Stufe 1 des qwen-code Daemon-Designs . Alle Routen befinden sich unter der Basis-URL des Daemons (Standard http://127.0.0.1:4170).

Diese Referenz beschreibt HTTP-Routen und SSE-Framing. Lesen Sie sie zusammen mit dem typisierten Ereignisschema für Payload-Verträge, Resync-Gründe und History-Anker, dem Event-Bus- und Replay-Leitfaden für Zustellung und Backpressure sowie Fähigkeiten und Versionierung für das bestehende v1-Protokoll und Kompatibilitätsregeln. Der Daemon-Dokumentationsindex verlinkt den vollständigen Vertragssatz.

Authentifizierung

Wenn der Daemon mit --token oder QWEN_SERVER_TOKEN gestartet wurde – oder nicht-loopback gebunden ist ohne beide, was ein ephemeres Bearer-Token generiert und es einmalig beim Start ausdruckt –, müssen alle normalen API-Routen außer /health bei gewöhnlichen Loopback-Bindungen Folgendes enthalten:

Authorization: Bearer <token>

Ohne konfiguriertes Token auf dem Loopback-Standard ist der Header optional, und Anfragen, die über den primären Listener eintreffen, haben volle Betreiber-API-Autorität. Workspace-Vertrauen, Sitzungsbesitz, X-Qwen-Client-Id, Berechtigungen, Funktionen, Validierung und Ressourcenprüfungen gelten weiterhin. Der Token-Vergleich erfolgt in konstanter Zeit. 401-Antworten sind einheitlich über missing header / wrong scheme / wrong token hinweg.

--open-with-auth. Dieser standardmäßig deaktivierte CLI-Modus erfordert eine Loopback-Bindung und ein verfügbares Web Shell. Er nutzt die normale --token-über-QWEN_SERVER_TOKEN-Auswahl oder generiert 32 zufällige Bytes, kodiert als base64url, vor dem Daemon-Start, wenn diese Auswahl leer ist. Der Browser erhält das ausgewählte Bearer-Token über #token= und speichert es pro Tab; das Protokoll und die Middleware sehen ein normales konfiguriertes Token. Die Fragmentzustellung basiert auf dem aufgelösten Token, nicht auf diesem Flag: Jeder --open-Start hängt das aufgelöste Bearer-Token – konfiguriert oder generiert – an das #token=-Fragment der gestarteten URL an (sichtbar für lokale Benutzer via ps / /proc, wie der Launcher warnt), sodass eine Nicht-Loopback-Bindung mit bloßem --open sein generiertes Bearer-Token auf dieselbe Weise an den Browser übergibt; die spezifischen Beiträge dieses Flags sind die Token-Generierung auf Loopback und der manuelle URL-Fallback für browserunfähige Umgebungen. Nur direkte eingebettete Aufrufer, die RunHandle.resolvedToken ignorieren, und Clients, die nie einen Browser starten, erhalten keine automatischen Zugangsdaten. In browserunfähigen Umgebungen wird die URL mit dem Geheimnis-Fragment zum manuellen Öffnen ausgegeben. Loopback /health und statische Web Shell-Assets behalten die unten beschriebenen Ausnahmen bei; --require-auth steuert weiterhin /health.

Der Kanal-Webhook-Eingang (POST /channels/:channelName/webhooks/:source) ist in jedem Modus getrennt von diesem Bearer-Vertrag. Wenn er gemountet ist, wird er vor bearerAuth registriert und authentifiziert sich mit seinem konfigurierten x-qwen-webhook-secret; das Rotieren des Daemon-Bearer-Tokens rotiert keine Webhook-Quellgeheimnisse.

/health-Ausnahme (Bctum): Bei Loopback-Bindungen (127.0.0.0/8 / localhost / ::1 / [::1]) wird /health VOR der Bearer-Middleware registriert, sodass Liveness-Probes im Pod das Token nicht tragen müssen, selbst wenn der Daemon mit --token gestartet wurde. Nicht-Loopback-Bindungen (--hostname 0.0.0.0 usw.) steuern /health zusammen mit den anderen normalen API-Routen – siehe den Abschnitt GET /health für die Begründung.

--require-auth (#4175 PR 15). Übergeben Sie dieses Flag beim Booten, um die Regel “Token erforderlich” auch auf Loopback auszudehnen. Das Booten schlägt fehl, wenn keine Token-Quelle aufgelöst werden kann – auf Loopback bedeutet das --token, QWEN_SERVER_TOKEN oder --open-with-auth (was sein eigenes generiertes Token vor dem Booten installiert, sodass --require-auth --open-with-auth startet). Das Fail-Fast gilt nur für Loopback: Eine Nicht-Loopback-Bindung löst das ephemere Bearer-Token auf, das sie generiert, wenn keine der konfigurierten Quellen vorhanden ist, und dies erfüllt das Flag. Die /health-Ausnahme wird in beiden Fällen aufgehoben, sodass /health ebenfalls Authorization: Bearer … erfordert.

Wenn das Flag aktiv ist, steuert die globale bearerAuth-Middleware jede normale API-Route – einschließlich /health und /capabilities. Der Kanal-Webhook-Eingang bleibt unabhängig durch gemeinsames Geheimnis authentifiziert, und Web Shell-Dokument- und Asset-Routen bleiben vor der Authentifizierung verfügbar. Ein nicht authentifizierter Client kann daher caps.features nicht vorab testen, um festzustellen, dass Authentifizierung erforderlich ist: Die Entdeckungsfläche für diesen Fall ist der 401-Antworttext selbst (einheitlich über bearer-gesteuerte Routen gemäß dem Abschnitt Authentifizierung). Das require_auth-Fähigkeitstag ist eine Bestätigung nach der Authentifizierung – sobald ein Client erfolgreich authentifiziert ist und /capabilities liest, bestätigt die Anwesenheit des Tags, dass der Daemon mit --require-auth gestartet wurde (nützlich für Audit-/Compliance-UIs und für SDK-Clients, um “diese Bereitstellung ist gehärtet” in einem Einstellungsfenster anzuzeigen). Strenge Mutationsrouten akzeptieren vertrauenswürdige Loopback-Anfragen vom primären Listener, bearer-authentifizierte Anfragen oder gepaarte Local Control-Anfragen. Nicht vertrauenswürdige tokenlose Einbettungen erhalten weiterhin 401 { code: "token_required", error: "…" }; mit --require-auth lehnt die globale Bearer-Middleware zuerst mit dem Legacy-Unauthorized-Text ab.

--allow-origin <pattern> (T2.4 #4514 ). Browser-Clients, die den Daemon cross-origin ansprechen, werden standardmäßig blockiert – eine Anfrage mit einem Origin-Header gibt 403 {"error":"Request denied by CORS policy"} zurück, da CLI/SDK-Clients nie Origin senden und der Daemon dessen Vorhandensein als Zeichen dafür wertet, dass die Anfrage aus einem Browser-Kontext stammt, in den der Betreiber nicht eingewilligt hat. Eine Ausnahme geht der Blockade bei einer Nicht-Loopback-Bindung mit Token voraus: Eine Same-Origin-Anfrage (Origin gleich dem direkten Socket-Schema plus der normalisierten Host-Autorität) wird bearer-authentifiziert und ihr Origin entfernt auf dem primären Listener – mit einem gültigen Bearer folgt der Status der Route selbst, mit einem fehlenden oder ungültigen Bearer ein 401, außer den vor-authentifizierten Web Shell-Dokument-, /assets/*-, /manifest.webmanifest-, /sw.js- und /mcp-app-sandbox-Routen, die ohne Zugangsdaten bereitgestellt werden wie in allen anderen Modi – und nur Cross-Origin- oder nicht übereinstimmende Origin-Werte behalten den 403-Umschlag bei. Übergeben Sie --allow-origin <pattern> (wiederholbar) beim Booten, um eine Allowlist anstelle der Blockade zu installieren. Jedes Muster ist entweder:

• Das Literal * — akzeptiert jeden Ursprung. Risiko: Der Start wird verweigert, wenn * konfiguriert ist, aber kein Bearer-Token aufgelöst werden kann. Die Prüfung liest das aufgelöste Token — --token, QWEN_SERVER_TOKEN, das generierte Loopback-Token von --open-with-auth oder das ephemere Bearer-Token, das bei einer Nicht-Loopback-Bindung generiert wird, wenn keine der konfigurierten Quellen vorhanden ist — daher ist diese Verweigerung nur auf Loopback beschränkt. Die Boot-Nachricht gibt eine stderr-Warnung aus, wenn * in der Liste enthalten ist. Empfehlung: Kombinieren Sie dies mit --require-auth bei Loopback-Bindungen, damit auch /health durch das Bearer-Token geschützt wird — es ist standardmäßig vor der Bearer-Middleware auf Loopback registriert (damit k8s/Compose-Probes es ohne Token erreichen können), und eine *-Allowlist macht es für jeden Cross-Origin-Browser erreichbar. --require-auth lässt die Web Shell-Statische Assets (/, /assets/*, /manifest.webmanifest, /sw.js sowie /session/:id, /plugins, /channels, /live, /scheduled-tasks, /goals und /settings Dokumentnavigationen) weiterhin vor der Authentifizierung auf Loopback verfügbar — sie werden vor der Bearer-Middleware gemountet — daher bleiben sie unter einer *-Allowlist für jeden Cross-Origin-Browser lesbar; --no-web entfernt diese Oberfläche. Bei Nicht-Loopback-Bindungen ist das Bearer-Token bereits beim Start obligatorisch und /health ist dahinter registriert. Normale API-Routen sind durch Bearer-Tokens geschützt, der Channel-Webhook-Eingang behält sein eigenes Shared-Secret-Gate, und Web Shell-Statische Assets (/, /assets/*, /manifest.webmanifest, /sw.js sowie /session/:id, /plugins, /channels, /live, /scheduled-tasks, /goals und /settings Dokumentnavigationen) bleiben vor der Authentifizierung verfügbar, es sei denn, --no-web entfernt sie.
• Eine kanonische URL-Origin — <scheme>://<host>[:<port>]. Kein abschließender Schrägstrich, kein Pfad, keine Userinfo, keine Query. Der Start wird mit InvalidAllowOriginPatternError verweigert, wenn der Eintrag den Round-Trip new URL(pattern).origin === pattern nicht besteht; die Fehlermeldung nennt das ungültige Muster und die kanonische Form. Streng nach Absicht: Stille Normalisierung (z. B. das Trimmen eines abschließenden /) würde Tippfehler durchlassen und mehrdeutige Eingaben akzeptieren. Ohne ein aufgelöstes Token — was nach der Generierung eine Loopback-Bindung bedeutet — sind HTTP(S)-Einträge auf Loopback-Hosts beschränkt; eine Nicht-Loopback-Browser-Origin erfordert ein Token, da sie andernfalls die gesamte Operator-API einschließlich Codeausführung als Daemon-Benutzer steuern könnte. Explizite Browser-Erweiterungs-Origin behalten ihren bestehenden tokenlosen lokalen Automatisierungspfad. Beim Start wird die Autorität protokolliert, die jeder tokenlosen erlaubten Browser-Origin gewährt wird.

Übereinstimmende Origins erhalten die Standard-CORS-Antwortheader bei jeder Anfrage:

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 spiegelt die Origin der Anfrage wörtlich wider (Groß-/Kleinschreibung wie vom Browser gesendet) anstelle des Literals *, selbst unter dem Muster * — Browser-Caches speichern Antworten darauf gepaart mit Vary: Origin, und das Spiegeln lässt Raum, um in einer späteren Version Access-Control-Allow-Credentials hinzuzufügen, ohne das Schema zu ändern. Die exponierten Header ermöglichen es Browser-Clients, Retry-Hinweise zu beachten, die SSE-Epoche beizubehalten und akzeptierte physische Streams zu korrelieren. Access-Control-Allow-Credentials wird heute NICHT gesendet: Konfigurierte Daemon-Anmeldeinformationen verwenden Bearer-in-Authorization, was über Origin hinweg ohne credentials: 'include' funktioniert; vertrauenswürdige Loopback-Autorität benötigt keine Browser-Anmeldeinformationen.

OPTIONS-Preflight-Anfragen (OPTIONS mit Access-Control-Request-Method oder Access-Control-Request-Headers) werden kurzgeschlossen mit 204 No Content plus den oben genannten Headern. Dies ist das konventionelle CORS-Muster und ist sicher — der Preflight bestätigt nur, welche Methoden/Header der Daemon akzeptiert; die tatsächliche nachfolgende Anfrage führt weiterhin das Host-Gate aus und dann entweder das Bearer-/Listener-Autoritäts-Gate oder das Channel-Webhook-Shared-Secret-Gate, bevor Zustände gelesen oder geändert werden. Einfache OPTIONS-Anfragen von übereinstimmenden Origins fließen weiterhin downstream mit angehängten CORS-Headern.

Origins, die nicht zur Allowlist passen, erhalten weiterhin 403 {"error":"Request denied by CORS policy"} — dieselbe Hülle wie die Standardwand, sodass Clients, die die Antwort der Wand bereits geparst haben, keine Sonderbehandlung für Daemon-Bereitstellungen mit Allowlist benötigen. Der Ablehnungspfad sendet keine Access-Control-*-Header (der Browser würde sie ignorieren, und das Senden würde indirekt die Größe der Allowlist über die Anwesenheit von Headern bekannt geben).

Die konfigurierte Musterliste wird absichtlich NICHT in /capabilities wiedergegeben — ein Browser-Client kennt seine eigene Origin bereits (er hat schließlich den Daemon aufgerufen), und das Offenlegen der Liste würde einem unauthentifizierten Leser von /capabilities ermöglichen, jede vertrauenswürdige Origin aufzulisten (nützliche Reconnaissance für eine falsch konfigurierte Bereitstellung). SDK-Clients prüfen auf das caps.features.allow_origin-Tag für “dieser Daemon respektiert Cross-Origin-Browser-Anfragen”, ohne die spezifischen Origins kennen zu müssen.

Loopback-Self-Origin-Anfragen (z. B. wenn die Web Shell den Daemon auf derselben 127.0.0.1:port aufruft) werden von einem separaten Origin-Strip-Shim behandelt, der VOR der CORS-Middleware läuft und den Header Origin für 127.0.0.1:port / localhost:port / [::1]:port / host.docker.internal:port oder die exakte gebundene Loopback-Adresse und den Port entfernt. Er akzeptiert auch die schemabasierten portlosen Formen, die Browser für Standardports senden: http://host auf Port 80 und https://host auf Port 443. Diese Anfragen passieren unabhängig von der --allow-origin-Konfiguration — Operatoren müssen den eigenen Port des Daemons nicht auflisten, damit die Web Shell funktioniert.

Gängiges Fehlerformat

5xx-Antworten tragen die ursprünglichen Fehlerfelder code und data, wenn vorhanden (JSON-RPC-Stil — das ACP-SDK leitet {code, message, data} vom Agenten weiter):

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

Ungültiges JSON im Anfragekörper gibt zurück:

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

mit Status 400.

SessionNotFoundError für eine unbekannte Session-ID gibt zurück:

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

mit Status 404. Ein gleichzeitiger Schließvorgang verwendet code: "session_closing".

WorkspaceMismatchError für eine POST /session, deren cwd nicht zu einer registrierten Workspace normalisiert wird, gibt 400 zurück mit:

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

Verwenden Sie dies, um Abweichungen vorab zu erkennen: Lesen Sie workspaceCwd aus /capabilities und lassen Sie cwd in POST /session weg (es fällt auf die primäre Workspace zurück), oder wählen Sie eine aus workspaces[].cwd, wenn multi_workspace_sessions beworben wird.

POST /session über der konfigurierten Obergrenze --max-sessions des Daemons gibt 503 zurück mit einem Retry-After: 5-Header und:

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

Wenn die effektive daemonweite Gesamt-Obergrenze eine neue Session ablehnt — --max-total-sessions oder die unter limits.maxTotalSessions beschriebene Standardeinstellung — wird dasselbe Antwortformat mit "scope": "total" zurückgegeben.

Anhängende Verbindungen zu bestehenden Sessions werden NICHT auf die Obergrenze angerechnet, sodass Reconnects eines inaktiven Daemons auch bei Erreichen der Kapazität weiterhin funktionieren.

Wenn das Initialisierungsbudget des ACP-Kanals abläuft, bevor newSession dispatcht wird, gibt POST /session 504 zurück mit Retry-After: 5 und:

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

timeoutMs — und die numerische Endung von error — spiegeln das konfigurierte --initialize-timeout-ms-Budget des Daemons wider (die obigen Werte sind die Standardeinstellungen). Das vollständige sichere Wiederholungsformat oben wird nur für die einfache Session-Erstellung ausgegeben, wo die Kanalinitialisierung streng jeder dauerhaften Mutation vorausgeht: Auf diesem Pfad ist das Feld sideEffectPossible: false maßgeblich, weil die Initialisierung der ACP-Anfrage newSession vorausgeht, und ein Client, der diesen strukturierten Vertrag versteht, kann nach der angegebenen Verzögerung wiederholen, ohne das Risiko einer doppelten Session einzugehen.

Anfragen, die branch oder worktree enthalten, sowie Initialisierungs-Timeouts, die von mutierenden Routen außer der einfachen Erstellung zurückgegeben werden (z. B. POST /session/:id/branch und POST /session/:id/side-task, bei denen ein committeter Fork den fehlgeschlagenen Handshake überleben kann), geben dasselbe 504 mit code: "init_timeout", phase und timeoutMs zurück — aber OHNE Retry-After, retryable oder sideEffectPossible. Für diese ist das Ergebnis der Mutation unbekannt: Die Vorbereitung von Branch und Worktree verändert Git vor der Initialisierung des Kanals, und der bei einem Fehler versuchte Rollback ist best-effort (ein fehlgeschlagener Checkout-Rollback belässt den Workspace auf dem neuen Branch, und ein erneuter Versuch kann einen Konflikt wegen eines bereits existierenden Branches auslösen). Clients, die alle 5xx-Mutationsantworten als mehrdeutig klassifizieren, bleiben konservativ fail-closed und sollten dieselbe Richtlinie auf die reduzierte Form anwenden. POST /session/:id/load und POST /session/:id/resume zeigen dieselbe reduzierte init_timeout 504 an, wenn die Kanalinitialisierung timeoutet, bevor die Restore-Anfrage gesendet wird (die ensureChannel-Phase); im Gegensatz zu den in ihren Errors-Listen dokumentierten session_restore_timeout 504 enthält diese Form kein Retry-After, kein retryable und installiert keinen Fence, da der Restore nie gesendet wurde. Der Dispatch-Timeout für newSession bei POST /session ist eine Ausnahme: Er gibt 504 mit code: "init_timeout", retryable: true und einem budgetbasierten Retry-After zurück, aber ohne phase oder sideEffectPossible, da das Ergebnis der Erstellung mehrdeutig ist. Alle anderen Timeout-Bezeichnungen behalten das generische Mapping bei.

RestoreInProgressError — ausgegeben von POST /session/:id/load, POST /session/:id/resume oder einer caller-supplied-id POST /session, wenn eine andere Registrierung bereits diese ID besitzt — gibt 409 zurück und:

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

Wird ausgelöst, wenn ein session/load für eine ID herausgegeben wird, für die bereits ein session/resume läuft (oder umgekehrt), oder wenn ein Spawn mit caller-supplied-id gegen eine der beiden Restore-Richtungen rennt. Warten Sie mindestens Retry-After Sekunden und versuchen Sie es erneut. Races bei gleicher Aktion (load vs. load, resume vs. resume) werden zusammengeführt, statt einen Fehler zu werfen, während der Restore aktiv ist.

reason unterscheidet zwei Fences, die diesen Code teilen, und der Retry-After-Header verfolgt dies:

Die öffentliche Restore-Anfrage wird durch limits.sessionRestoreTimeoutMs gesteuert (Standardwert 60 s). Nach einem 504 bleibt die ID gefencet, bis die späte ACP-Anfrage und die Bereinigung abgeschlossen sind. Ein Client, der weiterhin im üblichen 5-Sekunden-Takt wiederholt, würde gegen einen 409-Fehler laufen, den er nicht klären kann — beachten Sie den budgetbasierten Hinweis, der mit awaiting_abandoned_cleanup einhergeht.

SessionWorkspaceConflictError — ausgegeben von POST /session/:id/load und POST /session/:id/resume, wenn die angeforderte cwd auf einen registrierten Workspace abzielt, dieselbe Session-ID jedoch bereits live ist oder von einer anderen Runtime wiederhergestellt wird — gibt 409 zurück mit:

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

Clients sollten mit dem besitzenden Workspace erneut versuchen oder warten, bis der laufende Restore abgeschlossen ist, bevor sie die ID in einen anderen Workspace wiederherstellen. Races beim Restore innerhalb desselben Workspaces nutzen weiterhin das restore_in_progress-/Coalescing-Verhalten der Bridge.

SessionArchivedError wird ausgegeben, wenn ein Caller versucht, eine Session zu laden oder fortzusetzen, deren JSONL unter chats/archive/ liegt:

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

mit Status 409.

SessionArchivingError wird ausgegeben, wenn für dieselbe ID bereits ein Übergang zum Archivieren oder Entarchivieren einer Session läuft:

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

mit Status 409 und Retry-After: 5.

Fähigkeiten

Der Daemon bewirbt seine unterstützten Feature-Tags aus der Serve-Capability-Registry. Clients müssen die UI über features steuern, nicht über mode (gemäß Design §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']

Bedingte Tags erscheinen nur, wenn ihre Deployment- oder Laufzeitverfügbarkeitsbedingung erfüllt ist (siehe Tabelle unten). Der permission_mediation-Tag von F3 ist immer aktiv und trägt modes: ['first-responder', 'designated', 'consensus', 'local-only'], damit SDK-Clients den vom Build unterstützten Satz introspektieren können; die zur Laufzeit aktive Strategie befindet sich unter body.policy.permission.

session_startup_config bewirbt optionale startupConfig: { modelServiceId, reasoningEffort? } bei gewöhnlicher und eigenständiger Erstellung. Prüfen Sie dieses Tag stets vorab: Ältere Routen für die gewöhnliche Erstellung ignorieren das Objekt möglicherweise stillschweigend. modelServiceId ist erforderlich (1–256 Zeichen); reasoningEffort akzeptiert none, default, low, medium, high, xhigh oder max, sofern vom ausgewählten Modell unterstützt. Das Weglassen wendet nur das Modell an, ohne Reasoning-Setter oder implizites default. Das Objekt kann nicht mit dem Legacy-top-level-modelServiceId oder explizitem einzelnen Scope kombiniert werden und impliziert einen neuen Thread. Beim Start werden keine gemeinsamen Standardwerte gespeichert; das spätere Session-Verhalten bleibt unverändert.

Erfolg umfasst modelApplied: true und startupConfigApplied: { modelServiceId, reasoningEffort?, effectiveReasoning? }. Der Modellauswahlmechanismus ist kanonisch. Nur explizite Reasoning-Anforderungen enthalten die beiden Reasoning-Felder; der effektive Zustand ist { state: 'disabled' }, { state: 'provider-default' } oder { state: 'enabled', effort? } (Reasoning per Toggle allein hat keinen Aufwand). Ungültige Struktur führt zu 400 invalid_startup_config; eine abgelehnte oder unbestätigte Auswahl führt zu 422 startup_config_rejected. Eine definitive Ablehnung im eigenständigen Modus rollt ihre eigene Aufzeichnung zurück und versucht, das leere Ausgabeverzeichnis zu verwerfen, bevor sie zurückgibt; ein Aufzeichnungs-Rollback, dessen Entfernung nicht bestätigt werden kann, und transiente Startfehler behalten standalone_creation_outcome_unknown bei, während ein fehlgeschlagenes Verzeichnis-Verwerfen nur protokolliert wird und die definitive Ablehnung dennoch zurückgegeben wird. Ein Bestätigungsfehler im Erfolgsbody im SDK ist ein Protokollfehler, keine Anweisung, eine wiederhergestellte Session zu übernehmen.

session_scope_override ist der Verhandlungsgriff für das feldbezogene sessionScope-Feld bei POST /session (siehe unten). Ältere Daemons ignorieren das Feld stillschweigend, daher sollten SDK-Clients caps.features für dieses Tag vorab prüfen, bevor sie es senden.

session_id_override ist der Verhandlungsgriff für das optionale caller-supplied sessionId bei POST /session und ACP session/new-Metadaten. Clients müssen bestätigen, dass caps.features dieses Tag enthält, bevor sie das Feld senden, da ältere Daemons es möglicherweise stillschweigend ignorieren.

persistent_workspace_registration bewirbt dauerhafte Registrierung für Workspaces, die zur Laufzeit hinzugefügt wurden. POST /workspaces akzeptiert { "cwd": "/absolute/path", "persist": true }; Erfolg umfasst persisted: true. Registrierungen sind auf den kanonischen primären Workspace des Daemons unter dem Qwen-Home-Verzeichnis des Benutzers beschränkt und werden beim nächsten Daemon-Start wiederhergestellt. Das Weglassen von persist behält die prozesslokale Registrierung bei. GET /workspace-registrations listet den gespeicherten gewünschten Satz auf, und DELETE /workspace-registrations/:id vergisst einen Eintrag für den nächsten Neustart, ohne eine aktive Runtime hot zu entfernen.

workspace_display_name bewirbt optionale displayName-Eingaben bei POST /workspaces, Workspace-Metadaten-Aktualisierungen über PATCH /workspaces/:workspace und optionale Anzeigename-Felder in Workspace-Projektionen. Namen nehmen nicht an Suche oder Routing teil: id und kanonisches cwd bleiben die einzigen Selektoren, und doppelte Namen sind erlaubt.

workspace_runtime_removal bewirbt die synchrone Hot-Entfernung über DELETE /workspaces/:workspace. Capability-Workspace-Einträge fügen optionale removable hinzu; nur Zeilen mit removable: true können entfernt werden. Die Entfernung vergisst auch jeden persistenten Registrierungsalias für die Laufzeitumgebung, löscht aber niemals Dateien, Einstellungen, Transkripte oder Archive.

workspace_runtime bewirbt GET /workspace/runtime/status, POST /workspace/runtime/ensure und deren /workspaces/:workspace/runtime/...-Äquivalente. ensure akzeptiert keine Capability-Auswahl: Es startet oder wiederverwendet die ACP-Laufzeitumgebung des ausgewählten vertrauenswürdigen Workspaces und gibt deren Lebenszyklusstatus und monotone Laufzeit-Epoche zurück. Die primären Routen gehören nur der primären Laufzeitumgebung; qualifizierte Routen lösen nur die ausgewählte registrierte Laufzeitumgebung auf und fallen niemals zurück. Ein erfolgreiches Ensure erneuert das zehnminütige Keepalive-Fenster der Laufzeitumgebung. Status ist schreibgeschützt und startet das Kind niemals. Gleichzeitige Ensures teilen sich einen physischen Start. Ein laufender Start oder ein Fehler gibt wiederholbare 503 runtime_still_starting oder 503 runtime_initialization_failed zurück. Die Vorbereitung der Capability kann fortgesetzt werden, nachdem das Beobachtungsbudget für Ensure abgelaufen ist; in diesem Fall gibt Ensure weiterhin die aktive Laufzeitumgebung mit einem Nicht-Bereit-Capability-Zustand für die Statusabfrage zurück. Die Capability wird nur beworben, wenn alle aktiven Laufzeitbrücken den maßgeblichen Lebenszyklus-Snapshot bereitstellen; eine ausgewählte Legacy-Injektionsbrücke gibt 501 workspace_runtime_not_supported anstelle eines geschätzten Zustands oder einer Epoche zurück.

workspace_runtime_stop bewirbt unabhängig davon das benutzergestützte Stoppen der Laufzeitumgebung. GET /workspaces/runtime-stop-options ist eine schreibgeschützte, prozessglobale Vorschau: Sie umfasst die Anzahl der committeten Kinder, die modellierten Kinder-Obergrenzen sowie Sitzungen, blockierte Gründe, Kanal-ID, Epoche, aktuelles Stop-Token und letzte Quittung jedes sichtbaren Workspaces. Gewöhnliche geladene Sitzungen können explizit gestoppt werden; unabhängige ACP-Clients, aktivierte Zeitpläne, ausstehende Scheduler-/Management-/Start-Arbeit, Speicheraufgaben, Worker, Voice- und Spezial-Laufzeitumgebungen sind blockiert. POST /workspaces/:workspace/runtime/stop verwendet das strenge Mutations-Gate und nur die ausgewählte vertrauenswürdige Laufzeitumgebung. Senden Sie confirmInterruptions: true, expectedChannelId, expectedRuntimeEpoch, expectedStopToken und das exakte expectedSessionIds aus der Vorschau. Fallen Sie niemals auf die primäre Laufzeitumgebung zurück. Die Vorschau und jede Quittung listen die aktiven ACP-Kanäle der Laufzeitumgebung als channels (channelId, runtimeEpoch, optional executionEngine) auf; eine Laufzeitumgebung kann einen Kanal pro Ausführungs-Engine haben, und ein Stopp deckt alle ab. channelId benennt den ersten aufgelisteten Kanal und runtimeEpoch ist die neueste aufgelistete Epoche, sodass ein nach der Vorschau gestarteter Kanal die Bestätigung veraltet macht.

Eine erfolgreiche Antwort hat state: "stopped", stopped: true und released: true, nach bestätigtem Schließen von Sitzungen und Freigabe des Prozess-Registrierungseintrags für jedes aufgelistete Kind. Registrierung, Dateien und gespeicherter Verlauf bleiben erhalten. Antworten enthalten betroffene, unterbrochene, geschlossene und verbleibende Sitzungs-IDs. Veraltete oder blockierte Bestätigungen sind HTTP 409 (workspace_runtime_stop_stale / workspace_runtime_stop_blocked); teilweises Schließen ist 409 workspace_runtime_stop_incomplete; laufender oder fehlgeschlagener Teardown ohne nachgewiesene Freigabe ist 503 workspace_runtime_stop_in_progress / workspace_runtime_stop_failed; nicht unterstütztes Management ist 501 workspace_runtime_stop_not_supported. Ein unsauberer Teardown, der später die Registrierungsfreigabe nachweist, kann 200 mit einer Fehlerwarnung zurückgeben; unbestätigtes Session-Flush gibt weiterhin ein Teilfehler-/Fehlerergebnis zurück. Das gesamte Beobachtungs-/Schließbudget beträgt 60 Sekunden. Wenn es abläuft, während das Schließen einer Sitzung noch läuft, wird die Antwort mit state: "failed" und 503 workspace_runtime_stop_failed abgeschlossen; die Bereinigung wird separat fortgesetzt. Der ausgewählte Workspace bleibt isoliert und sein Kind wird bis zum tatsächlichen Abschluss der Bereinigung weitergezählt, obwohl der Aufrufer einen Fehler empfangen hat. Schreibgeschützte Optionen können später stopped nach bestätigten Schließungen und nachgewiesener Freigabe oder incomplete melden, wenn die Persistenz nicht bestätigt wurde; das bereits zurückgegebene Fehler-Snapshot ändert sich nicht. Wenn das Budget stattdessen zwischen Sitzungs-Schließungen erschöpft ist, wird die Antwort mit state: "incomplete" und 409 workspace_runtime_stop_incomplete abgeschlossen: Es wird kein weiteres Schließen oder erzwungenes Beenden gestartet, die Zulassungssperre des Stopps wird freigegeben (das überlebende Kind wird wie üblich weitergezählt), und das Stoppen der verbleibenden Sitzungen erfordert eine neue Vorschau und Bestätigung. Eine Ablehnung des Flushes wird nicht durch erzwungenes Beenden der verbleibenden Sitzungen umgangen. Der Exit des Root-Prozesses oder ein Rückgang der globalen Prozessanzahl allein begründet keine Freigabe des ausgewählten Kindes. Unter Windows, wo die Registrierung keine Nachkommen-Prozessgruppen verfolgt, ist der abgeschlossene Exit des Roots der Freigabenachweis, daher beweist released: true dort nicht, dass der Prozessbaum verschwunden ist.

Wiederholte Bestätigung des zuletzt konsumierten Tokens beobachtet denselben Vorgang. Eine neue Bestätigung kann einen unvollständigen Stopp erneut versuchen, wobei das Token rotiert; ältere konsumierte Tokens werden dann veraltet. Wenn eine Antwort verloren geht, lesen Sie Optionen und stimmen Sie die neueste Quittung anhand von Workspace und Stop-Token ab, anstatt ein anderes Ziel zu stoppen. Quittungen können nach Entfernung, Vertrauensänderungen oder Neugestaltung des Daemons/der Brücke nicht verfügbar sein; Abwesenheit lässt das Ergebnis unbekannt und autorisiert niemals die Fortsetzung. SDK runtimeStopOptions() und workspaceById(id).stopRuntime(confirmation) verwenden REST auch bei einem ACP-Transport und wiederholen POST niemals automatisch. Sitzungsteilnehmer erhalten session_closed mit reason: "client_close" und cause: "workspace_runtime_stop"; fatale stoppbezogene Exits markieren zusätzlich persistenceUnconfirmed: true. Aktualisierte Web Shell-Clients behalten die gespeicherte Auswahl/das Transkript und warten auf ein explizites Fortsetzen. Dies ist ein einmaliger Stopp, keine persistente Aussetzung; ein Client, der das Ereignis verpasst hat, kann erneut um Kapazität konkurrieren.

Status- und Ensure-Antworten der Laufzeitumgebung verwenden dieses Format:

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

Wenn eine Workspace-Laufzeitumgebung mehr als eine Ausführungs-Engine hat, beschreiben runtimeLive und runtimeEpoch den Kanal, der die Workspace-Steuerung bedient (MCP und Skills): Solange dieser Kanal aktiv ist, ändern sie sich nicht, wenn eine andere Engine startet oder beendet wird. state meldet diesen Kanal als cold, starting oder stopping, solange er nicht aktiv ist; active und idle zählen Arbeit auf jeder Engine.

capabilities.skills.state ist not_started, starting, ready, stale oder error; Fehler enthalten {code, message} in capabilities.skills.error. Ein Skills-Katalog ist nur dann aktuell, wenn die Top-Level- und Capability-runtimeEpoch-Werte übereinstimmen. revision ordnet die Skills-Vorbereitung innerhalb einer Laufzeit-Epoche und darf nicht über Epochen hinweg verglichen werden.

workspace_skills_config_runtime bewirbt die geteilten Skills-Lesevorgänge und Konfigurationsmutationen unter /workspace/{config,runtime}/skills und /workspaces/:workspace/{config,runtime}/skills. Die Web Shell verwendet diese Routen für das Skills-Management und beim Komponieren einer neuen Sitzung, um Slash-Befehle aus der Konfiguration unmittelbar vor dem Ersetzen durch einen Laufzeitkatalog mit passender Epoche zu füllen. Wenn die Funktion fehlt, müssen Clients weiterhin die Legacy-Skills-Routen verwenden und dürfen Ensure der Laufzeitumgebung nicht ausschließlich für Skills aufrufen.

session_load und session_resume bewerben die expliziten Wiederherstellungsrouten (POST /session/:id/load und POST /session/:id/resume). Ältere Daemons geben für diese Pfade 404 zurück, daher sollten SDK-Clients caps.features vor dem Aufruf prüfen. unstable_session_resume wird weiterhin als veralteter Alias beworben, um Kompatibilität mit SDKs zu gewährleisten, die ausgeliefert wurden, während die zugrunde liegende ACP-Methode connection.unstable_resumeSession hieß; neue Clients sollten auf session_resume prüfen.

limits.sessionRestoreTimeoutMs ist, wenn vorhanden, das Wanduhr-Budget des Daemons für die zugrunde liegende ACP loadSession / unstable_resumeSession-Anfrage. Es ist ein additives v1-Feld. Das TypeScript SDK gibt dem Daemon 10 Sekunden Client-Spielraum, und der Web Shell Watchdog gibt ihm 15 Sekunden; Clients, die mit einem älteren Daemon kommunizieren, sollten jeweils 70 Sekunden und 75 Sekunden verwenden.

session_transcript bewirbt GET /session/:id/transcript, eine schreibgeschützte, seitenweise Replay-Ansicht über die persistierte JSONL der aktiven Sitzung. Sie ist getrennt von /load: Sie hängt keinen Client an, speist den Live EventBus nicht, erstellt keine Live-Sitzung und ändert nicht das Live-Replay-Fenster. Clients sollten sie verwenden, wenn sie das vollständige On-Disk-Transkript einer langen Sitzung benötigen, und /load nur für begrenztes Live-Replay während der kalten UI-Wiederherstellung verwenden.

workspace_persisted_transcript bewirbt GET /workspaces/:workspace/session/:id/transcript, einen daemon-lokalen, nur-persistierten Pager, der ACP nicht startet, keinen Live-Bridge-Zustand abfragt, keine Einstellungen lädt, keine Projektfähigkeiten entdeckt und nicht den Legacy-Persistenz-Cursor-Schlüssel erstellt. Das Tag ist bedingungslos, da vertrauenswürdige Einzel-Workspace-Primaries die Plural-Route nutzen können; die Workspace-spezifische Vertrauensautorisierung wird weiterhin bei jeder Anfrage geprüft. Registrierte nicht vertrauenswürdige sekundäre Workspaces dürfen lesen, während ein nicht vertrauenswürdiger Primär-Workspace weiterhin abgelehnt wird.

workspace_session_export bewirbt GET /workspaces/:workspace/session/:id/export, einen nur-vertrauenswürdigen Vollexport der aktiven persistierten Sitzung des ausgewählten Workspaces. Er ist unabhängig von session_export und workspace_qualified_rest_core: Veröffentlichte Daemons können beide älteren Tags bewerben, ohne die Plural-Route zu implementieren, daher müssen Clients dieses Tag direkt vorab prüfen (Pre-flight). Das Tag ist bedingungslos, da ein vertrauenswürdiger Einzel-Workspace-Primär-Client die Route nach ID oder CWD nutzen kann. Der Export löst keinen Live-Eigentümer auf, startet kein ACP, hängt keinen Client an und fällt nicht auf einen anderen Workspace zurück.

workspace_archived_session_export bewirbt GET /workspaces/:workspace/session/:id/archive/export, einen nur-vertrauenswürdigen Vollexport aus dem archivierten persistierten Speicher des ausgewählten Workspaces. Er ist unabhängig von workspace_session_export und workspace_qualified_rest_core; Clients müssen dieses Tag direkt vorab prüfen. Eine separate Route verhindert, dass ein älterer Daemon die Archivierungsabsicht ignoriert und ein aktives Transkript mit derselben ID zurückgibt.

workspace_session_live_state bewirbt GET /workspaces/:workspace/sessions/live-state, einen nur-vertrauenswürdigen, speicherbasierten Snapshot der Live-Sitzungen der Laufzeitumgebung des ausgewählten Workspaces sowie eine In-Memory-Katalogversion, die Clients signalisiert, wann ein vollständiger Neuladen des persistierten Katalogs gerechtfertigt ist. Er ist unabhängig von workspace_qualified_rest_core: Veröffentlichte Daemons können die breitere Workspace-REST-Fähigkeit bewerben, ohne diese Route zu implementieren, daher müssen Clients dieses Tag direkt vorab prüfen. Das Tag ist bedingungslos, da ein vertrauenswürdiger Einzel-Workspace-Primär-Client die Route nach ID oder CWD nutzen kann; die Workspace-spezifischen Vertrauensprüfungen gelten weiterhin bei jeder Anfrage, und die Route erweitert die permissive Lese-Richtlinie für den persistierten Katalog nicht-vertrauenswürdiger Sekundär-Workspaces nicht auf den Live-Bridge-Zustand. Das Tag bedeutet, dass der Endpunkt existiert; es verspricht nicht, dass jedes Live-Element den optionalen updatedAt Aktivitäts-Wasserzeichen trägt, welches lebenszyklusabhängig ist.

workspace_session_live_state_batch bewirbt POST /sessions/live-state. Clients prüfen dies einmal vorab vor dem Batching von Abfragen und behalten die Einzel-Workspace-Route für ältere Daemons bei. Der Batch verwendet dieselben nur-vertrauenswürdigen, speicherbasierten Snapshot- und Katalogversions-Semantiken wie die Einzel-Workspace-Route.

Das optionale Top-Level-Feld /capabilities sessionLiveStatePollIntervalMs bewirbt das Daemon-weite Polling-Intervall für den Live-Zustand in Millisekunden. Es wird einmal aus der Start-Umgebungsvariable QWEN_SESSION_LIVE_STATE_POLL_INTERVAL_MS aufgelöst, unabhängig von Workspace-Umgebungs-Overlays. Ganzzahlwerte von 1000 bis 2147483647 werden akzeptiert; fehlende oder ungültige Werte verwenden 5000. Die Web Shell nutzt diesen Hinweis für alle Workspace-Live-Zustands-Abfragen und greift auch auf 5000 zurück, wenn das Feld bei einem älteren oder inkompatiblen Daemon fehlt oder ungültig ist. Dieses Feld ändert nicht die Snapshot-Semantik der Route, sofortige lokale/Sichtbarkeits-Aktualisierungen oder das vollständige Katalog-Polling. SDK-Clients sind weiterhin für ihre eigenen Timer verantwortlich.

slow_client_warning deckt das SSE-Backpressure-Verhalten ab: (a) Der Daemon sendet ein slow_client_warning synthetisches Event-Stream-Frame, wenn der Live-Frame-Rückstand eines Abonnenten oder der live serialisierte Byte-Rückstand 75 % voll überschreitet, einmal pro Überlauf-Episode (nach dem Abfließen beider Messungen unter 37,5 % wieder scharf geschaltet); (b) GET /session/:id/events akzeptiert einen ?maxQueued=N Query-Parameter (Bereich [16, 2048]), um den Frame-Rückstand pro Abonnent für kalte Reconnects gegen einen großen Replay-Ring vorzubelegen. Die Obergrenze für serialisierte Bytes wird vom Daemon verwaltet (Standard 2 MiB pro Abonnent), ist nur live relevant und hat absichtlich keinen Query-Parameter. Die Daemon-weite Ringgröße wird durch --event-ring-size gesteuert (Standard 8000, gemäß #3803 §02). Ältere Daemons fehlen stillschweigend die Warn-/Query-Funktionen — prüfen Sie dieses Tag vorab, bevor Sie sich dafür entscheiden.

typed_event_schema bewirbt Daemon-Ereignis-Nutzlasten, die dem KnownDaemonEvent Schema des SDK entsprechen. Ältere Daemons streamen möglicherweise weiterhin kompatible Frames, aber SDK-Clients sollten dieses Tag vorab prüfen, bevor sie typisierte Ereignisabdeckung voraussetzen.

client_heartbeat bewirbt POST /session/:id/heartbeat. Ältere Daemons geben 404 zurück; prüfen Sie dieses Tag vorab, bevor Sie periodische Heartbeats senden.

session_close und session_metadata bewerben DELETE /session/:id und PATCH /session/:id/metadata. Ältere Daemons geben 404 zurück; prüfen Sie diese Tags vorab, bevor Sie Schließen- oder Umbenennen-Funktionen bereitstellen.

session_organization bewirbt benutzerdefinierte Sitzungsgruppen und Pinnen. Es fügt GET/POST/PATCH/DELETE /workspace/:id/session-groups, PATCH /session/:id/organization und die opt-in organisierte Listenansicht GET /workspace/:id/sessions?view=organized hinzu. Wenn sowohl session_organization als auch workspace_qualified_rest_core beworben werden, ist auch die workspace-qualifizierte Organisations-Mutation PATCH /workspaces/:workspace/session/:id/organization verfügbar. Die Legacy-Mutation bleibt primär-workspace-spezifisch. Ältere Daemons geben 404 für die Mutations-/Gruppen-Routen zurück und ignorieren den Vertrag für die organisierte Ansicht, daher müssen WebShell/SDK-Clients diese Tags vorab prüfen, bevor sie die entsprechende Gruppierungs- oder Pinning-UI anzeigen.

session_archive bewirbt die v1 Directory-State-Archiv-API: POST /sessions/archive, POST /sessions/unarchive und GET /workspace/:id/sessions?archiveState=active|archived. Archivierte Sitzungen können nicht geladen oder fortgesetzt werden, bis sie dearchiviert sind. session_archive_idle_guard bewirbt die additive requireIdle Archiv-Option: Die besitzende Laufzeit prüft, ob aktive Arbeit unmittelbar vor Beginn des Schließens als idle bestätigt ist, und belässt andernfalls das aktive Transkript an Ort und Stelle. session_storage_conflict_repair bewirbt die additive resolveConflicts Anfrage-Option und den unten beschriebenen resolvedConflicts Antwort-Bucket.

workspace_qualified_rest_core bewirbt mehrere Kern-REST-Routen unter /workspaces/:workspace/.... Der Selektor wird zuerst als exakte Workspace-ID aufgelöst, dann als URL-kodierter absoluter Pfad (cwd) nach der Kanonisierung. Neuere Single-Workspace-Daemons beinhalten die primäre Laufzeitumgebung in workspaces[], auch wenn multi_workspace_sessions fehlt, sodass Clients die für workspace-qualifizierte Routen erforderliche ID ermitteln können; Clients sollten auf ältere Daemons, die das Array weglassen, zu capabilities.workspaceCwd zurückfallen. Vertrauensstatus- und Vertrauensanforderungs-Routen sind für registrierte nicht vertrauenswürdige Workspaces verfügbar; der qualifizierte Hooks-Status-Lesevorgang (GET /workspaces/:workspace/hooks) wird ebenfalls für registrierte nicht vertrauenswürdige Workspaces bereitgestellt, da er die ausstehende Projekt-Hooks-Vertrauensentscheidung meldet, was zur qualifizierten Genehmigungs-Mutation passt; Datei-Lese-Routen folgen der bestehenden Dateisystem-Lese-Richtlinie. Registrierte nicht vertrauenswürdige sekundäre Workspaces bieten zudem nur persistierte Session- und Session-Group-Kataloge an: Diese Lesevorgänge binden keine Session an, starten kein ACP und führen keinen Live-Bridge-Status zusammen. Dateischreibvorgänge, Katalog-Mutationen und andere mehrere Kern-Routen erfordern einen vertrauenswürdigen Workspace, es sei denn, eine separate Fähigkeit dokumentiert eine engere Richtlinie: workspace_persisted_transcript (nur lesend) oder die Vertrauensgewährungs-Mutation, die für einen registrierten nicht vertrauenswürdigen Workspace akzeptiert wird, unabhängig davon, ob workspace_trust_grant beworben wird — dieses Tag meldet nur, ob der Hot-Reload des Vertrauens verdrahtet ist, sodass eine aufgezeichnete Entscheidung die laufende Laufzeitumgebung ohne Daemon-Neustart erreichen kann; es meldet nie, ob die Route bedient wird. Ein nicht vertrauenswürdiger Primär-Workspace erhält weiterhin 403 { code: "untrusted_workspace" } von den mehreren Katalog- und Transkript-Routen; Legacy-Single-Primär-Routen behalten ihr bestehendes Kompatibilitätsverhalten bei. Dieses Tag deckt die Kernflächen für Dateien, Status, Einstellungen, Berechtigungen, Vertrauen, Lebenszyklus, MCP-Steuerung, Tool- und Skill-Toggles, Speicher, Workspace-Agent-CRUD und Session-Speicherung ab. Es deckt nicht Authentifizierung, Sprache, Erweiterungen, ACP/WebSocket-Transport, Kanal-Worker-Routing oder workspace-qualifizierte Session-Exporte ab; prüfen Sie vorab workspace_session_export oder workspace_archived_session_export separat. Workspace-Vertrauen ist keine ACL: Ein Client mit dem Daemon-Token kann jede registrierte Workspace-Fläche lesen, die durch diese Richtlinie erlaubt ist.

workspace_qualified_voice bewirbt Voice-Routen, die von einer vertrauenswürdigen Workspace-Laufzeitumgebung ausgewählt werden: GET und POST /workspaces/:workspace/voice, POST /workspaces/:workspace/voice/transcribe und WS /workspaces/:workspace/voice/stream. Es wird nur beworben, wenn sowohl Multi-Workspace-Laufzeitumgebungen als auch der gemeinsame ACP/Voice-WebSocket-Listener aktiviert sind. Der Selektor folgt denselben Regeln für ID oder kodierten absoluten Pfad wie andere mehrere Routen. Bei REST gibt ein unbekannter Selektor 400 { code: "workspace_mismatch" } zurück und ein nicht vertrauenswürdiger Selektor gibt 403 { code: "untrusted_workspace" } zurück; die WebSocket-Upgrade-Ablehnung legt den entsprechenden HTTP-400/403-Status ohne strukturiertes JSON-Envelope offen. Keiner der Transports fällt auf primär zurück. Legacy /workspace/voice, /workspace/voice/transcribe und /voice/stream bleiben primär-only. Clients verwenden workspace_qualified_voice für alle qualifizierten Voice-Modalitäten und lassen die ausgewählte Laufzeitumgebung konfigurationsspezifische Fehler melden. Die Legacy-Tags workspace_voice, workspace_voice_transcription und voice_transcribe beschreiben nur die primärgebundenen Routen und dürfen eine qualifizierte sekundäre Konfiguration nicht verbergen.

workspace_qualified_memory bewirbt die workspace-qualifizierten Managed-Memory-Routen: POST /workspaces/:workspace/memory/{remember,forget,dream} stellt Aufgaben in die Warteschlange und GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId liest sie zurück. Es wird nur beworben, wenn sowohl ACP HTTP als auch Multi-Workspace-Laufzeitumgebungen aktiviert sind. Der Selektor folgt denselben Regeln für ID oder kodierten absoluten Pfad wie andere mehrere Routen. Jeder registrierte Workspace erhält seine eigene Aufgabenspur; die qualifizierte Spur des Primären ist dieselbe Instanz wie die Single-Fläche /workspace/memory, sodass eine Aufgabe, die in eine eingestellt wurde, in der anderen lesbar ist. Die Auflösung erfolgt streng pro ausgewählter Laufzeitumgebung ohne Primär-Fallback: Ein unbekannter Selektor gibt 400 { code: "workspace_mismatch" } zurück, ein nicht vertrauenswürdiger Selektor gibt 403 { code: "untrusted_workspace" } zurück und eine inaktive oder drainende Laufzeitumgebung gibt 503 { code: "workspace_runtime_unavailable" } zurück. Lesevorgänge weisen niemals eine Spur zu, daher gibt das Abfragen eines Workspaces ohne Aufgaben 404 { code: "<kind>_task_not_found" } zurück. Task-IDs sind auf ihre Spur beschränkt und überleben weder eine Workspace-Rekonfiguration noch einen Laufzeitumgebungs-Ersatz; eine veraltete ID gibt 404 zurück, keinen Datenverlust-Zustand. Wenn ACP HTTP deaktiviert ist, wird das Tag nicht beworben und eine nicht-primäre qualifizierte Anfrage gibt einen nicht wiederholbaren 501 { code: "workspace_memory_unavailable" } zurück, während die qualifizierte Primär-Route über die lokal verwaltete Spur weiter funktioniert.

session_lsp bewirbt GET /session/:id/lsp, den nur lesenden strukturierten LSP-Status-Snapshot für Daemon-Clients. Ältere Daemons geben 404 zurück; prüfen Sie dieses Tag vorab, bevor Sie den Remote-LSP-Status anzeigen.

session_resources bewirbt GET /session/:id/resources, ein nur lesendes Paar bereinigter Skill- und MCP-Snapshots, erstellt aus der Config der ausgewählten Live-Session. Die Route ist auf den Besitzer der Live-Session beschränkt: Sie fällt niemals auf die primäre Laufzeitumgebung zurück und leitet die Ressourcen der Session nicht aus dem Workspace-Status ab. Die verschachtelten Objekte skills und mcp wiederverwenden die entsprechenden Workspace-Status-Payloads, lassen jedoch MCP-Authentifizierung, Pool-, Workspace-Budget- und Workspace-Discovery-Fehler-Anreicherungen weg. Status, Discovery und Buchhaltung, die vom MCP-Manager der ausgewählten Session gemeldet werden, bleiben vorhanden. Ältere Daemons geben 404 zurück; prüfen Sie dieses Tag vorab, bevor Sie einen Session-Ressourcen-Katalog anzeigen.

session_status bewirbt GET /session/:id/status, die Live-Bridge-Zusammenfassung für eine einzelne Session per ID. Zusätzlich zu clientCount und hasActivePrompt bieten Live-Sessions isWaitingForPermission, isWaitingForUserQuestion, pendingInteractionCount und ein beibehaltenes turnError nach einem fehlgeschlagenen Turn an. Der Fehler wird gelöscht, wenn der nächste Prompt tatsächlich startet. Eine Live-Session, die einen laufenden Turn in der aktuellen Bridge abgeschlossen hat, trägt auch updatedAt, denselben Aktivitäts-Wasserzeichen, der unter der Live-State-Route dokumentiert ist; da diese Route die Bridge-Zusammenfassung direkt zurückgibt, wird der Wert nicht mit der mtime des persistierten Transkripts zusammengeführt und kann früher sein als derjenige, den eine Session-Liste meldet. Sowohl die Einzel-Session-Statusantwort als auch die Workspace-Session-Listen enthalten turnError und pendingInteractions: renderbereite Berechtigungsaktionen oder ask_user_question Fragen plus die requestId und auswählbaren Optionen, die von den bestehenden Berechtigungs-Voting-Routen benötigt werden. Jede Benutzerfrage hat ein answerKey; stimmen Sie mit answers ab, zum Beispiel { "0": "Polling" }, indiziert nach diesem Wert. Nur-persistierte Sessions lassen den Runtime-Status weg, weil keine Laufzeitumgebung existiert. Ältere Daemons geben 404 zurück; prüfen Sie dieses Tag vorab, bevor Sie den Status einer einzelnen Session abfragen, anstatt die gesamte Session-Liste zu scannen.

session_info bewirbt GET /workspace/:id/session-info und seinen Zwilling /workspaces/:workspace/session-info. Die Antwort aggregiert persistierte aktive und archivierte Session-Anzahlen, ohne Listen-Metadaten zu hydratisieren. Es handelt sich um einen expliziten O(n)-Disk-Scan, der nicht abgefragt werden darf; Clients sollten truncated: true als Untergrenzen-Ergebnis behandeln.

session_approval_mode_control, workspace_tool_toggle, workspace_skill_settings_toggle, workspace_skill_settings_batch_toggle, extension_batch_activation_v2, workspace_init und workspace_mcp_restart geben die unten dokumentierten Mutationssteuerungsrouten an. Die Steuerung des Genehmigungsmodus behält ihr Nicht-Strict-Kompatibilitätsgate bei. Die anderen Steuerungen sind durch Operator-Autorität streng geregelt: Vertrauenswürdige Loopback-Primär-, Bearer-authentifizierte oder gepaarte Local-Control-Anfragen bestehen. Eine tokenlose Primäranfrage, die das strenge Gate ohne vertrauenswürdige Loopback-Autorität erreicht, gibt 401 token_required zurück; fehlende oder ungültige konfigurierte Anmeldeinformationen und ungepaarte Local-Control-Anmeldeinformationen werden früher von der Bearer-Middleware mit einfachem 401 Unauthorized abgelehnt. Daemons, denen eine dieser Routen fehlt, geben 404 zurück. Die einstellungsspezifischen Skill-Tags unterscheiden sich: Daemons aus der Generation der eingestellten Tags werben workspace_skill_toggle und workspace_skill_batch_toggle an und bedienen ihren katalogvalidierten Vertrag unter denselben Pfaden. Die eingestellte Einzelspezifikationsroute kann HTTP 404 skill_not_found oder 409 skill_not_toggleable zurückgeben; die eingestellte Batch-Route gibt HTTP 200 zurück und platziert katalogabgeleitete Fehler in errors[]. Führen Sie vor dem Exponieren einer affordance einen Pre-Flight für jedes Tag durch und leiten Sie den einstellungsspezifischen Skill-Vertrag nicht durch das Testen der Routenerreichbarkeit ab. Die Routenpfade und Anfragebodies haben sich nicht geändert.

mcp_guardrails (Issue #4175  PR 14) deckt die MCP-Budget-Oberfläche ab: die Felder clientCount / clientBudget / budgetMode / budgets[] auf GET /workspace/mcp, das Feld disabledReason auf Serverzellen sowie die CLI-Flags --mcp-client-budget / --mcp-budget-mode. Ältere Daemons lassen die neuen Felder vollständig weg; SDK-Clients führen einen Pre-Flight dieses Tags durch, bevor sie sich auf budgets[]-Semantik verlassen. Der Registry-Deskriptor enthält auch modes: ['warn', 'enforce'] für zukünftige Feature-Mode-Exposure – derzeit leiten Clients den Modus aus dem Feld budgetMode des Snapshots ab. Die Serververweigerung im enforce-Modus ist deterministisch nach der Deklarationsreihenfolge von Object.entries(mcpServers); eine zukünftige Scope-Präzedenzschicht (falls qwen-code eine übernimmt) würde dies zu “niedrigste Präzedenz zuerst” verschieben, um die Konvention plugin < user < project < local von claude-code widerzuspiegeln.

Der Umfang ist fähigkeitsgesteuert. Mit mcp_workspace_pool teilen sich Sitzungen innerhalb einer Workspace-Runtime einen Transportpool und WorkspaceMcpBudget, und der Snapshot emittiert budgets[0].scope: 'workspace'. Unterschiedliche Workspace-Runtimes besitzen unabhängige Pools. Ohne das Tag verwendet jede ACP-Sitzung ihre Legacy-McpClientManager, der Snapshot emittiert scope: 'session', und N Sitzungen können jeweils die konfigurierte Obergrenze verbrauchen.

workspace_file_read deckt die Workspace-Datei-Routen für Text/Liste/Stat/Glob ab (GET /file, GET /list, GET /glob, GET /stat). workspace_file_bytes deckt GET /file/bytes ab, das später hinzugefügt wurde, damit Clients die Unterstützung für Raw-Byte-Fenster gegen PR19-era Daemons vorab prüfen können. workspace_file_write deckt die hash-bewussten Text-Mutationsrouten ab (POST /file/write, POST /file/edit). Das Write-Tag bedeutet, dass der Routenvertrag existiert; es bedeutet nicht, dass die aktuelle Bereitstellung für anonyme Mutationen offen ist. Schreiben/Bearbeiten sind strikte Mutationsrouten und erfordern Betreiber-Autorität; tokenloser vertrauenswürdiger Loopback qualifiziert sich. workspace_file_upload deckt POST /file/upload ab, die Binär-Ingress-Route: Ein application/octet-stream-Body, begrenzt auf MAX_UPLOAD_BYTES (50 MiB), wird in den Workspace geschrieben, ohne jemals zu überschreiben – ein belegter Name wird automatisch nummeriert (name (1).ext, name (2).ext, …). Es ist auch eine strikte Mutationsroute.

workspace_file_delete deckt nur POST /workspaces/:workspace/file/delete ab; es existiert keine Legacy-Primary-/file/delete-Route. Der JSON-Body ist { "path": "relative/file.txt" }, und Erfolg gibt { "kind": "file_delete", "path": "relative/file.txt" } zurück. Diese strenge Mutationsroute entfernt dauerhaft eine reguläre Datei aus dem ausgewählten vertrauenswürdigen lokalen Workspace. Verzeichnisse und Symlinks werden abgelehnt; nicht unterstützte Fabriken (einschließlich SSH) geben 422 zurück. Die Fähigkeit beschreibt Protokollunterstützung, nicht die Erlaubnis zum Löschen in jedem Workspace. Clients müssen auch workspace_qualified_rest_core preflighen.

Wenn workspace_qualified_rest_core beworben wird, ist dieselbe Dateioberfläche auch unter /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 und /workspaces/:workspace/file/delete verfügbar (die letzte Route erfordert zusätzlich workspace_file_delete).

workspace_directory_create und workspace_directory_delete bewerben unabhängig voneinander POST /workspaces/:workspace/directory/create und POST /workspaces/:workspace/directory/delete. Preflight das Tag der Operation zusammen mit workspace_qualified_rest_core; ältere qualifizierte Daemons könnten diese Routen fehlen. Beide sind strenge Mutationen, die dem vertrauenswürdigen aktiven ausgewählten lokalen Runtime gehören, ohne Primary-Fallback oder Legacy-Primary-Gegenstück. Erstellung ist exklusiv unter einem vorhandenen Elternelement; Löschung ist permanent und rekursiv.

Dasselbe Tag exponiert auch workspace-qualifiziertes Projekt-Agent-CRUD unter /workspaces/:workspace/agents und /workspaces/:workspace/agents/:agentType. Diese Plural-Routen lesen oder mutieren nur Projekt-Level-Agenten für den ausgewählten Workspace; global- und user-Scope-Anfragen geben 400 { code: "global_scope_not_supported_for_workspace_route" } zurück. Workspace-lose /workspace/agents-Routen behalten ihr bestehendes Primary-Workspace-Verhalten bei und bleiben die einzige REST-Oberfläche für den User-Level-Agent-Scope.

extension_management_v2 bewirbt einen User-Level-Erweiterungskatalog und eine Mutationsoberfläche unter /extensions/*, plus Workspace-Aktivierungsprojektionen unter /workspaces/:workspace/extensions/*. Artefakte sind global; Workspace-Routen exponieren nur Lesevorgänge von Projektionen, exakte Aktivierungsüberschreibungen und Runtime-Aktualisierungen. Lesevorgänge können auf einen nicht vertrauenswürdigen registrierten Workspace zielen, während Aktivierung, Aktualisierung und Workspace-gestützte Installation ein vertrauenswürdiges Ziel erfordern. Langsame Mutationen verwenden Daemon-lokale Operationen unter /extensions/operations/:operationId; Store-Generation, nicht Operationsverlauf, ist über Neustarts hinweg und über Daemons hinweg maßgeblich. Die veröffentlichte workspace_extensions-Fähigkeit und die /workspace/extensions/*-Routen bleiben ein Kompatibilitätsadapter für den Primary-Workspace. Clients müssen extension_management_v2 preflighen und dürfen es nicht aus dem Daemon-Modus oder workspace_qualified_rest_core ableiten.

extension_git_credentials bewirbt authentifizierte HTTPS-Git-Installationen sowohl auf POST /workspace/extensions/install als auch auf POST /extensions/install. Clients müssen dieses Tag preflighen, bevor sie URL-Userinfo oder credentialPersistence senden; ältere Daemons lehnen URL-Anmeldeinformationen ab. Das Tag beschreibt Backend-Protokollunterstützung, nicht die Verfügbarkeit eines Schlüsselbunds: Der gespeicherte Modus meldet das ausgewählte Backend im Terminal-Operationsergebnis.

extension_local_path_install bewirbt Daemon-lokale Erweiterungsquellen sowohl auf POST /workspace/extensions/install als auch auf POST /extensions/install. Der Pfad source muss ein absoluter Pfad sein, der auf dem Daemon-Host existiert. Relative Pfade bleiben nicht unterstützt, damit das cwd des Daemon-Prozesses nicht die Quellenidentität ändern oder eine GitHub-owner/repo-Kurzform verdecken kann. Die bestehende Installationsoperation kopiert die Erweiterung in den verwalteten Speicher; sie verknüpft die Quelle nicht. Clients müssen dieses Tag preflighen, da ältere Daemons lokale Quellen ablehnen.

extension_batch_activation_v2 fügt PUT /extensions/activation und PUT /workspaces/:workspace/extensions/activation hinzu. Beide akzeptieren 1–100 Namen in extensionNames, deduplizieren sie unter Berücksichtigung der Groß-/Kleinschreibung, wobei die Reihenfolge des ersten Auftretens beibehalten wird, speichern geänderte Ziele in einer Generation und geben einen einzelnen 202-Operationshandle zurück. Ein Ziel muss nicht installiert sein, wenn enabled oder disabled festgelegt werden: Sein Name erstellt eine Sollzustandsdeklaration, die erhalten bleibt, wenn eine Extension mit diesem Namen installiert wird. Die globale Route akzeptiert state: "enabled" | "disabled" und schreibt V2 defaultActivation; die Workspace-Route akzeptiert auch "inherit" und wendet exakte Überschreibungen für die ausgewählte vertrauenswürdige Laufzeitumgebung an oder löscht sie. inherit deklariert keinen unbekannten Namen, und ein Löschen aller unbekannten Namen meldet updated: false.

extension_activation_explicit_refresh bedeutet, dass einzelne und Batch-Aktivierungsoperationen nach dem dauerhaften Policy-Commit abgeschlossen sind, ohne aktive Sitzungen direkt zu aktualisieren. Aufrufer, die eine sofortige Anwendung benötigen, sollten auf den Erfolg der Aktivierung warten und dann entweder die synchrone Haupt-Workspace-POST /workspace/extensions/refresh übermitteln, die Aktualisierungszählungen direkt zurückgibt, oder die asynchrone POST /workspaces/:workspace/extensions/refresh des ausgewählten Workspaces, die einen separaten Operationshandle zurückgibt. Die beiden Formen sind nicht austauschbar: Die asynchrone Operation zeichnet die angewendete Generation auf, wenn ihre vollständige Laufzeitabstimmung abgeschlossen ist, während die synchrone Route nichts aufzeichnet, sodass der Generations-Reconciler diesen Workspace weiterhin als ausstehend behandelt und seine Sitzungen beim nächsten Durchlauf erneut aktualisiert. Aufrufer, die einen bestimmten Workspace adressieren können, sollten die asynchrone Form bevorzugen. Ein Fehler bei der Aktualisierung rollt das Aktivierungsergebnis nicht zurück und degradiert es nicht. Daemons ohne diese Fähigkeit beinhalten bereits die Laufzeitaktualisierung in der Aktivierung, daher dürfen Kompatibilitätsclients keine zweite Aktualisierung übermitteln. Der unabhängige 30-Sekunden-Generations-Reconciler bleibt aktiviert und wendet die committete Policy normalerweise beim nächsten Durchlauf an; fehlgeschlagene Abstimmungen werden durch spätere Durchläufe wiederholt.

Extension Management V2 Wire-Vertrag

Alle Routen verwenden die oben genannten Daemon-Bearer-Authentifizierungsregeln. X-Qwen-Client-Id ist für die V2-Mutationsrouten optional; wenn angegeben, muss es einen Client identifizieren, der bei einer der Ziel-Laufzeitumgebungen der Mutation registriert ist. :extensionId ist die Kleinbuchstaben-64-Hex-Extension-Identität. :workspace wird zuerst als exakte Workspace-ID aufgelöst und andernfalls als URL-kodierter absoluter cwd nach der Kanonisierung.

Explizite Extension-Aktualisierung

Fähigkeitskennung: workspace_session_refresh für die optionale Sitzungsauswahl. Sowohl POST /workspace/extensions/refresh (Haupt-Laufzeitumgebung) als auch POST /workspaces/:workspace/extensions/refresh (ausgewählte Laufzeitumgebung) akzeptieren:

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

Das Weglassen von sessionIds bewahrt die vollständige Laufzeitaktualisierung. Ein übergebenes Array wird in Anfragereihenfolge dedupliziert, und [] aktualisiert keine Sitzungen oder Bootstrap-Caches. IDs müssen nicht leere Zeichenketten sein. Ungültige Anfrageformate geben HTTP 400 zurück; unbekannte IDs, einschließlich Sitzungen, die einem anderen Workspace gehören, geben HTTP 404 zurück, bevor die Arbeit beginnt. Das Eigentum an der Sitzung wird nur innerhalb der aufgelösten Laufzeitumgebung überprüft, ohne Fallback auf die Haupt-Laufzeitumgebung. Bestehende Authentifizierungs-, strenge Mutations-, Workspace-Vertrauens- und Client-Identitäts-Gates gelten.

Die Hauptroute gibt weiterhin HTTP 200 mit { refreshed, failed } zurück; die qualifizierte Route gibt weiterhin HTTP 202 mit einem Operationshandle zurück. Zählungen beschreiben die ausgewählten Sitzungen. Eine Aktualisierung mit sessionIds erhöht die workspace-weit angewendete Generation nicht, selbst wenn die Auswahl alle aktuellen Sitzungen abdeckt. Die automatische vollständige Abstimmung bleibt unverändert und kann andere Sitzungen später aktualisieren. Die Auswahl erstellt keine sitzungsspezifische Aktivierungsrichtlinie: Gemeinsame Laufzeit-Caches können sich ändern, und Workspace-Ereignisse bleiben workspace-weit.

Clients müssen workspace_session_refresh vor der Übergabe des Felds prüfen, einschließlich eines leeren Arrays; ältere Daemons können es stillschweigend ignorieren. Bestehende Aufrufe ohne das Feld erfordern keine neue Fähigkeitsprüfung.

Workspace-Ressourcenzustand

Prüfen Sie extension_state unabhängig. Es unterstützt nur Skills; es impliziert kein MCP-Ressourcenmanagement. Beide Routen wählen die registrierte Workspace-Laufzeitumgebung aus und fallen niemals auf die Haupt-Laufzeitumgebung zurück. GET folgt den bestehenden schreibgeschützten Vertrauensregeln; PUT erfordert einen vertrauenswürdigen Workspace.

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

PUT akzeptiert 1–100 Einträge, einschließlich eines Einzel-Element-Batches. Es lehnt fehlerhafte Einträge, duplizierte Namen (unter Berücksichtigung der Groß-/Kleinschreibung) und nicht unterstützte Gruppen ab, bevor sie in die Warteschlange gestellt werden. Alle Namen müssen zur installierten Ziel-Extension gehören, einschließlich derzeit deaktivierter Skills; ein ungültiges Ziel lässt die Operation fehlschlagen, ohne teilweise Schreibvorgänge. Ein gesperrter Store-Commit führt die aufgelisteten Überschreibungen für den exakten kanonischen Workspace zusammen. Nicht aufgelistete Skills und andere Workspaces bleiben erhalten. Es gibt keinen Einstellungen-Schreibvorgang, keine Zukunftsnamensdeklaration oder keine implizite Aktivierung der übergeordneten Extension.

GET gibt v: 1, workspaceId, workspaceCwd, extensionId, name und skills zurück. Jeder Skill hat name, defaultEnabled, nullable workspaceEnabled, effectiveEnabled und optionales disabledReason/lockedScope. Das optionale skillStates des Manifests liefert Standardwerte; fehlende Werte standardmäßig auf aktiviert. Für eine aktive übergeordnete Extension ist die Priorität: hartes Deaktivieren in den Einstellungen, explizites Aktivieren in den Einstellungen, Standardmäßiges Deaktivieren in den Einstellungen, interne Workspace-Überschreibung, Manifest-Standardwert. Internes Deaktivieren verwendet disabledReason: "default" und sperrt die Einstellungen nie. Eine deaktivierte oder entfernte übergeordnete Extension kann nicht durch eine Skill-Überschreibung wiederbelebt werden.

Die set_extension_state-Operation gibt status: "updated" mit sortierten result.resourceStates.skills zurück; result.states behält seine Bedeutung für die Update-Prüfung bei. Persistierter Zustand ist kein Beweis dafür, dass jede Sitzung aktualisiert wurde. Der Daemon aktualisiert nur Skills und deren Befehls-/Modellkontext für die Ziel-Laufzeitumgebung, einschließlich Bootstrap- und Live-Sitzungen, ohne unrelated MCP/LSP/Hooks neu zu starten. Fehler beim Aktualisieren nach dem Commit erzeugen Warnungen, ohne den Zustand zurückzusetzen. Überschreibungen überleben Neustarts und Extension-Aktualisierungen und werden bei der Deinstallation entfernt. Clients dürfen nicht auf die Skill-Einstellungs-API zurückgreifen, da diese eine Einstellung mit höherer Priorität schreibt.

Globaler Katalog

Die Antwort des globalen Katalogs lautet:

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

installType wird weggelassen, wenn keine Installationsmetadaten verfügbar sind. defaultActivation ist enabled oder disabled. workspaceOverrideCount schließt gespeicherte inherit-Einträge aus.

Die Antwort der Workspace-Projektion lautet:

{
  "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 ist enabled, disabled oder null für Vererbung. activationSource ist default, workspace_override, legacy_path_rule oder cli_override. desiredGeneration ist die dauerhafte Store-Generation; appliedGeneration ist die neueste Generation, die der Controller als auf diese Workspace-Laufzeitumgebung angewendet aufgezeichnet hat, und kann vorübergehend hinterherhinken.

Installation erfordert ausdrückliche Zustimmung und eine initiale Aktivierung:

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

Verwenden Sie für die initiale Aktivierung nur im Workspace { "scope": "workspace", "workspaceId": "target-workspace-id" }; das Ziel muss existieren und vertrauenswürdig sein. Daemon-Installationen akzeptieren GitHub-, Git- und npm-Quellen. Wenn extension_local_path_install beworben wird, akzeptieren sie auch einen absoluten Pfad, der auf dem Daemon-Host existiert. ref gilt nicht für npm, ref und autoUpdate gelten nicht für lokale Quellen, und registry gilt nur für npm. ref, autoUpdate, allowPreRelease und registry sind optional.

Wenn extension_git_credentials beworben wird, kann eine HTTPS-Git-Quelle Benutzerinformationen enthalten, zum Beispiel https://username:token@git.example.com/org/repository.git. credentialPersistence ist nur mit einer solchen Quelle gültig. Es ist stored oder one_time und standardmäßig one_time, wenn es weggelassen wird. Im gespeicherten Modus speichert die daemon’s hybrid secret storage die Zugangsdaten und behält nur die saubere Repository-URL in den Installationsmetadaten, sodass die Extension aktualisierbar bleibt. Im einmaligen Modus werden weder die Repository-URL noch die Zugangsdaten gespeichert, und es wird eine nicht aktualisierbare snapshot erstellt; autoUpdate: true wird für diesen Modus abgelehnt. Die Angabe des Feldes ohne URL-Zugangsdaten, die Angabe ungültiger Zugangsdaten oder die Verwendung von Zugangsdaten mit npm-, Archiv-, lokalen, SSH- oder Nicht-Git-Quellen gibt 400 zurück.

Installationsantworten und -operationen mit Zugangsdaten geben credentialPersistence frei und können credentialStorage als keychain oder encrypted_file freigeben. Einmalige Operationen lassen source weg; gespeicherte Operationen können die saubere Quelle zurückgeben. Snapshot-Katalog-/Status-Einträge lassen die Quelle weg, setzen credentialPersistence auf one_time und melden not updatable. Das Update schlägt mit extension_not_updatable fehl; ein nicht verfügbares gespeichertes Geheimnis schlägt vor dem Netzwerkzugriff mit extension_credential_unavailable fehl.

Globale und Workspace-Aktivierungs-PUT-Anfragen verwenden denselben Body:

{ "state": "enabled" }

state ist enabled oder disabled. Anfragen für Update, Deinstallation, Update-Prüfung, Aktivierung löschen und Aktualisierung haben keinen erforderlichen Body.

Batch-Aktivierungsanfragen verwenden Extension-Namen:

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

Der Workspace-Batch akzeptiert auch "state": "inherit". Terminale globale Ergebnisse enthalten name und defaultActivation; Workspace-Ergebnisse enthalten name, workspaceActivation (null für Vererbung) und effectiveActivation. Ungültige Namen lehnen die Anfrage ab; Konflikte mit bestehenden Store-Identitäten schlagen atomar fehl, ohne teilweisen Commit. Ein unbekanntes inherit-Ziel wird nicht persistiert, da das Löschen einer Überschreibung keine Standardaktivierungsdeklaration erzeugen oder eine spätere Installationszustimmung ersetzen darf.

Jede akzeptierte asynchrone Mutation gibt Folgendes zurück:

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

Workspace-qualifizierte Mutationen verwenden denselben globalen /extensions/operations/:operationId-Polling-Pfad. Die Operationshistorie ist prozesslokal, behält nur eine begrenzte Anzahl terminaler Einträge und geht bei einem Daemon-Neustart verloren; Clients müssen den Katalog oder die Workspace-Projektion erneut lesen und Generationen vergleichen, wenn eine Operations-ID verschwindet.

Eine Operations-Snapshot hat diese Form:

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

status wechselt von queued zu running, dann zu succeeded, succeeded_with_warnings oder failed. Während der Ausführung ist phase preparing, committing oder reconciling. Terminaler Erfolg kann result enthalten, wobei status gleich installed, enabled, disabled, updated, uninstalled, checked oder refreshed ist; Reconciliation-Ergebnisse können zusätzlich refreshed, failed und error enthalten, während Batch-Aktivierungsergebnisse sortierte results enthalten. Update-Prüfungen geben result.states zurück, indiziert nach Extensionsnamen, mit Werten wie checking for updates, update available, up to date, not updatable oder error. Zugangsdaten und Autorisierungsheader sind niemals Operationsfelder.

Ein dauerhafter Commit gefolgt von unvollständiger Bereinigung oder Runtime-Reconciliation wird nicht als fehlgeschlagene Mutation gemeldet. Er gibt succeeded_with_warnings zurück und bewahrt das committete Ergebnis:

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

Warnung workspaceId und code sind optional; workspaceCwd und error sind immer vorhanden. Clients sollten Warnungen anzeigen, ihren Katalog/projection aktualisieren und dürfen die dauerhafte Mutation nicht blind wiederholen.

Validierungs- und Autorisierungsfehler sind synchrone HTTP-Fehler unter Verwendung von { "error": "...", "code": "..." }, wenn ein stabiler Code existiert. Wichtige Fälle sind 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 und 429 extension_queue_full. Die Installationsvalidierung gibt auch 400 für ungültige source/ref/registry-Optionen, fehlende Zustimmung oder fehlende/ungültige initiale Aktivierung zurück. Eine Mutation, die nach 202 fehlschlägt, wird dargestellt, während sie in der Operationshistorie behalten wird, mit status: "failed", error und einem optionalen stabilen code; häufige Codes umfassen extension_prepare_timeout und extension_conflict. HTTP 404 für eine Operation impliziert keinen Rollback, da die Operationshistorie nicht dauerhaft ist.

daemon_status bewirbt GET /daemon/status, den konsolidierten schreibgeschützten Diagnose-Snapshot des Betreibers, der unten dokumentiert ist.

daemon_update bewirbt die prozessglobalen GET /daemon/update-, POST /daemon/update/prepare- und POST /daemon/update/restart-Oberflächen.

scheduled_task_gate bewirbt das optionale gate auf POST und PATCH /scheduled-tasks sowie gate und gateStatus auf Task-Ansichten. Eine Gate ist ein Shell-Befehl, den die besitzende Sitzung bei jedem Auslösen außerhalb des Modells ausführt: Exit 0 mit Ausgabe liefert das Auslösen mit dieser angehängten Ausgabe, Exit 0 ohne stdout-Eintrag überspringt es, und ein Non-Zero-Exit wird gemeldet, wenn das Gate anfängt zu fehlschlagen, nicht bei jedem Auslösen. gateStatus.lastOutcome ist quiet, delivered, failed oder blocked.

• Ein Gate benötigt eine wiederkehrende Aufgabe: POST mit recurring: false oder ein PATCH, das ein Gate auf einer One-Shot setzt oder eine gated Aufgabe in One-Shot umwandelt, antwortet mit 400 gate_requires_recurring; eine bereits in diesem Zustand befindliche Aufgabe behält ihre anderen Änderungen bei. Ein fehlerhaftes Gate (leer bei POST, nur ein Kommentar, über 2048 Zeichen, ein NUL-Zeichen oder ein unpaariges UTF-16-Surrogat, ein Shell-Wrapper wie bash -c '…' oder jeder Teil, der mit & im Hintergrund ausgeführt wird) antwortet mit 400 invalid_gate. Die &-Prüfung ist lexikalisch und best-effort; im Zweifel lehnt sie ab (ein & in einem Kommentar, ein Heredoc-Body oder (( … ))), und ein Gate, das diese Prüfung passiert, wird als failed gemeldet, wenn es mit nichts auf stdout beendet wird, während ein Hintergrundteil noch seinen stdout hält (außerhalb der bwrap-Shell-Sandbox, deren PID-Namespace diesen Teil mit dem Befehl beendet). Bei PATCH, gate: null oder gate: "" wird das Gate und sein condition gelöscht.
• Eine Legacy-Aufgabe, geschützt durch ein condition, verweigert jeden gate-Schlüssel in einem PATCH mit 409 task_legacy_unsupported, sodass ein Client gate nur sendet, wenn er ihn ändert.
• Ein Gate, das über diese Routen geschrieben wird, trägt keine Bestätigung von der Sitzung. Es läuft unbeaufsichtigt nur dort, wo ein monitor-Aufruf desselben Befehls ohne Rückfrage laufen würde: unter einer gespeicherten Monitor(...)- oder Bash(...)-Allow-Regel, als schreibgeschützter Befehl oder in einer Auto- oder Yolo-Sitzung. Eine Deny-Regel blockiert es in jedem Modus und Plan-Modus blockiert es; ein blockiertes Auslösen endet mit blocked.
• Clients dürfen gate nicht an einen Daemon ohne dieses Tag senden: Ein solcher Daemon verwirft es auf POST und antwortet auf ein Gate-only PATCH mit 400 empty_patch.

autofix_pr_watches bewirbt GET /autofix-pr/watches (der primäre Workspace) und GET /workspaces/:workspace/autofix-pr/watches (ein registrierter, vertrauenswürdiger). Jeder beantwortet die /autofix-pr-Watches des Workspace-Klons so, wie qwen autofix-pr status sie auflistet, gelesen aus den Watch-Dateien unter dem Main-Worktree des Klons (.qwen/tmp), jede geöffnet ohne Link-Following und ohne Blockieren. Kein Lock wird genommen, GitHub wird nicht gefragt, und kein Git-Befehl läuft außer git worktree list, der den Klon findet. Die Antwort ist { v: 1, available, root?, now?, watches, unreadable? }: available ist false, ohne Watches, wenn kein Git-Repository für den Workspace gefunden wird (oder Git dort nicht laufen kann), und root ist der Main-Worktree des Klons, derselbe für zwei Workspaces eines Klons. Eine Watch trägt die Felder von status (Abschnitt 6.10 des /autofix-pr-Designs) aber thisSession, worktreePath, pushTarget, gitTrusted und worktreeWork; ihr session ist die Sitzung, die sie besitzt, was keine Sitzung dieses Daemons sein kann. Das Stoppen einer Watch ist Sache des Skills (/autofix-pr stop <n> in der besitzenden Sitzung); diese Routen ändern nichts.

Bedingte Tags. Diese Feature-Tags werden nur beworben, wenn ihr Deployment-Toggle, Runtime-Wiring oder Verfügbarkeitszustand aktiv ist. Die Anwesenheit des Tags bedeutet, dass das dokumentierte Verhalten verfügbar ist; die Abwesenheit bedeutet entweder einen älteren Daemon vor Einführung des Tags oder einen aktuellen Daemon, bei dem dieser Zustand falsch ist. Derzeit:

Live-Voice verwendet standardmäßig auf jeder Plattform den Web-Shell-Endpunkt (realtime_voice_web, WS /live/web). Der native macOS-Host ist opt-in: Nur ein macOS-Daemon, der mit QWEN_SERVE_LIVE_NATIVE_HOST=1 gestartet wurde, bewirbt realtime_voice, registriert WS /live/host und installiert den Host, wenn Live aktiviert ist. Ohne dies meldet /live/setup nativeHost: false mit einem nicht wiederholbaren install-Fehler, und POST /live/setup/install und POST /live/setup/launch antworten mit 409 live_native_host_unavailable.

Ein Browser-Host beantwortet host.capture_visual nur, solange der Benutzer einen Bildschirm mit der Seite teilt, was die Seite in ihrem Hello als selfChecks.screenShare meldet. Teilen ist eine separate, explizite Handlung – das Modell fragt mitten im Turn, und getDisplayMedia erfordert eine Benutzer-Geste –, daher hält die Seite den Stream und nimmt pro Anfrage ein Frame. Wenn nichts geteilt wird, antwortet sie sofort mit success: false, statt die Anfrage timeouten zu lassen.

Da eine Seite nicht auf das Dateisystem des Daemons schreiben kann, sendet sie nur das JPEG. Der Daemon ignoriert jedes screenshotPath, das ein Browser-Lease meldet, und speichert das Bild selbst unter einem von ihm gewählten Namen im selben privaten Capture-Verzeichnis, in das ein nativer Host schreibt. Ein nativer Host persistiert weiterhin sein eigenes PNG und übergibt den Pfad wie zuvor.

mcp_guardrails ist nicht in dieser bedingten Tabelle enthalten – es ist ein immer aktives Tag, das beworben wird, wenn die Binärdatei die neuen /workspace/mcp-Budget-Felder unterstützt, unabhängig davon, ob der Operator ein Budget konfiguriert hat. Operatoren, die --mcp-client-budget nicht festgelegt haben, erhalten dennoch die neuen Felder (mit budgetMode: 'off', budgets: []).

mcp_guardrail_events (Issue #4175  PR 14b) bewirbt die typisierten SSE-Push-Ereignisse, die Überschreitungen des MCP-Budgets ohne Polling-Schleife sichtbar machen. Zwei Frame-Typen treffen auf GET /session/:id/events ein:

• mcp_budget_warning – feuert einmal beim Überschreiten der 75%-Schwelle von reservedSlots.size / clientBudget nach oben. Wird erst wieder aktiviert, nachdem das Verhältnis unter 37,5 % fällt (MCP_BUDGET_REARM_FRACTION). Spiegelt die Hysterese von slow_client_warning aus PR 10, jedoch auf Manager-Ebene statt auf Ebene des Backlogs pro Abonnent. Payload: { liveCount, reservedCount, budget, thresholdRatio: 0.75, mode: 'warn' | 'enforce' }. Tritt sowohl im warn- als auch im enforce-Modus auf; niemals im off-Modus.
• mcp_child_refused_batch – feuert am Ende jedes discoverAllMcpTools*-Durchlaufs, wenn ein oder mehrere Server abgelehnt wurden, UND als Batch der Länge 1 beim readResource-Lazy-Spawn-Ablehnungspfad. Payload: { refusedServers: [{ name, transport, reason: 'budget_exhausted' }, ...], budget, liveCount, reservedCount, mode: 'enforce' }. mode ist das wörtliche 'enforce', da der warn-Modus niemals ablehnt.

Beide Ereignisse befinden sich im SSE-Replay-Ring pro Sitzung (sie tragen ein id), sodass ein Client, der sich mit Last-Event-ID neu verbindet, über sie hinweg fortsetzt; der Snapshot bei GET /workspace/mcp bleibt die maßgebliche Quelle für den Zustand nach einer verlängerten Trennung. Immer aktiv, sobald beworben – es gibt keinen bedingten Schalter. Der SDK-Reducer-Zustand (DaemonSessionViewState) stellt mcpBudgetWarningCount, lastMcpBudgetWarning, mcpChildRefusedBatchCount, lastMcpChildRefusedBatch für Adapter bereit, die eine einfache Lag-basierte UI wünschen.

Routen

Clients können session_turn_status per Feature-Detection ermitteln und GET /session/:id/turns/current oder GET /session/:id/turns/:promptId abfragen. Diese Routen erfordern die aktive besitzende Session und laden oder scannen niemals einen anderen Workspace. Abgeschlossene Ergebnisse sind best-effon Transcript-Aufzeichnungen, die aus dem aktiven Zweig mit einem begrenzten Scan gelesen werden; prompt_not_found bedeutet, dass kein Ergebnis in der Live-Warteschlange, im Terminal-Overlay mit 64 Einträgen oder im begrenzten aktiven Fenster gefunden wurde. resultText ist die rohe finale Antwort des Elternmodells nach der letzten Tool-Grenze, vor optionaler Nachrichtenumschreibung, und kann fehlen. Ergebnisse mit mehr als 32.768 UTF-16-Codeeinheiten enthalten resultTruncated: true und resultCode: "RESULT_TEXT_TRUNCATED".

GET /health

Liveness-Probe. Die Standardform gibt 200 {"status":"ok"} zurück, wenn der Listener läuft – günstig, ohne Bridge-Zugriff, geeignet für hochfrequente Liveness-Probes in k8s/Compose.

Übergeben Sie ?deep=1 (akzeptiert auch ?deep=true oder bloßes ?deep) für eine Daemon-weite Probe, die Bridge-Zähler über jede verwaltete Workspace-Laufzeitumgebung aggregiert, einschließlich eines Workspaces, der noch entleert wird (nur informativ, keine echte Liveness-Prüfung):

{
  "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 und activePrompts sind Summen. activeWork ist wahr, wenn irgendeine Laufzeitumgebung eine akzeptierte, aber nicht abgeschlossene Prompt hat (einschließlich einer FIFO-wartenden Prompt), einen laufenden Hintergrund-Agenten, eine wartende/in Bearbeitung befindliche Agent-Terminal-Benachrichtigung, Session-verwaltete Hintergrund-Shell- oder Workflow-Arbeit oder eine kind-owned Session-Runde. Die aggregierten session-Halte umfassen Ziel- und Cron-Verarbeitung, Historienänderungen sowie wartende oder laufende Monitor-Fortsetzungen; Vordergrund-Prompts bleiben Daemon-eigen. Laufende Monitore, Follow-up-Vorschläge und externe Prozesse, die die Shell-Registrierung nicht mehr verfolgen kann, bleiben außerhalb des Feldes. Es ist sessionbezogen: Kanalarbeit ohne zugeordnete Session – ein Spawn in Arbeit, eine ausstehende Wiederherstellung, MCP-Erkennung oder Authentifizierung – wird nicht gezählt, sodass activeWork falsch lesen kann, während der Daemon sich weigert, diesen Kanal freizugeben. Lesen Sie dieses Feld nicht als “der Daemon ist freigebbar”; es beschreibt nur session-eigene Arbeit. activeWorkReporting gibt an, wie viel dieser Booleschen tatsächlich gedeckt ist: full, wenn jede Live-Session durch einen frischen Bericht eines Kindes abgedeckt ist, das alle erforderlichen Kategorien meldet, none, wenn keine Session das Melden ausgehandelt hat, und partial für alles dazwischen – einschließlich eines veralteten Snapshots oder eines ausgehandelten Kindes, das eine erforderliche Kategorie auslässt. Ein Snapshot, der älter als drei Berichtsintervalle ist, zählt nicht mehr als Abdeckung: Er ist kein Bericht darüber, dass die Session im Leerlauf ist, daher liest sich die Session wieder als gehalten, genau so, als hätte das Kind nie berichtet. Gewöhnliche automatische Bereinigung ist auch für ein ausgehandeltes, aber unvollständiges Kind deaktiviert; ein Kind, das shell oder session nicht versteht, kann das bedingte Schließen gemäß dem vollständigen aktuellen Prädikat nicht sicher autorisieren. Komplett nicht unterstützte historische Kinder behalten das Legacy-Bereinigungs-Verhalten bei, und explizites Schließen, Beenden, Herunterfahren und Kanal-Exit bleiben Zwangsoperationen. activeWorkStaleMs ist das Alter des ältesten Snapshots, auf dem der Boolesche Wert beruht unter den abgedeckten Sessions, und ist 0, wenn keine Session abgedeckt ist; es ist diagnostisch, da die Frische bereits vom Daemon in activeWorkReporting eingestuft wird (nur der Daemon kennt die ausgehandelte Kadenz jedes Kanals). Die Einstufung wird einmal über jede verwaltete Laufzeitumgebung berechnet, nicht pro Laufzeitumgebung und dann kombiniert – eine Laufzeitumgebung ohne Sessions ist vakuös vollständig, und dies als Beweis zu betrachten, würde es einem leeren Workspace erlauben, für nicht gemeldete Sessions eines anderen Workspaces einzustehen. lastActivityAt ist die letzte Nicht-Null-Workspace-Aktivitätszeit und idleSinceMs wird aus diesemselben Snapshot abgeleitet. channelAlive bedeutet, dass mindestens ein verwalteter Workspace-Kanal live ist; es bedeutet nicht, dass jeder Workspace gesund ist. connectedClients und das optionale rateLimitHits bleiben Daemon-weite Zähler statt Summen pro Workspace.

Neustart-Controller sollten den Daemon als beschäftigt betrachten, wenn:

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

Das Weglassen des dritten Terms macht activeWork === false ununterscheidbar von “kein Kind hat mir etwas gesagt”, was der einzige Fall ist, in dem Handeln darauf unsicher ist. Unbekannte Antworten und fehlgeschlagene Probes müssen ebenfalls einen Neustart verhindern. activePrompts bleibt ein unabhängiges Kompatibilitätssignal.

Diese Felder sind ein Beobachtungs-Cache, kein Neustart-Lease: Selbst eine frische, vollständig eingestufte, leere Antwort beschreibt den Moment, in dem sie erfasst wurde, und Arbeit kann unmittelbar danach beginnen. Die obige Regel senkt das Risiko eines falschen Neustarts erheblich, eliminiert es aber nicht – strenge Sicherheit erfordert einen Prepare-Restart-Zaun, der die Zulassung neuer Arbeit stoppt, die Entleerung bestätigt und erst dann herunterfährt.

⚠️ Die Tiefenprüfung ist informativ, keine echte Liveness-Verifizierung oder ein atomarer Reclaim-Lease. Ausgehandelte ACP-Kinder veröffentlichen kanalweite Active-Work-Snapshots in einer ausgehandelten Kadenz, und der Daemon bewertet ihre Aktualität als activeWorkReporting — aber er beendet niemals einen Kanal aufgrund eines fehlenden Berichts, da die Stille einer Sitzung kein Beweis dafür ist, dass der Prozess gestorben ist. Transport-Liveness und Erkennung blockierter Agenten sind separate Mechanismen. connectedClients zählt REST-SSE-Verbindungen, nicht jeden ACP-Transport. Verwenden Sie wiederholte Stichproben und sauberes Herunterfahren für Idle-Reclamation; verwenden Sie authentifizierte /daemon/status für Transport- und Workspace-Diagnosen. Wenn ein Getter des verwalteten Runtimes eine Ausnahme auslöst, schlägt der Deep Health Check mit 503 {"status":"degraded","reason":"aggregation_failed"} fehl (fail-closed), anstatt teilweise Summen zurückzugeben, und das Daemon-Log identifiziert den fehlerhaften Workspace-Runtime. Während des Bootstraps, bevor die Runtime-Registry bereit ist, gibt es 503 {"status":"degraded","reason":"bootstrap"} mit Retry-After: 1 zurück. Für Listener-Liveness verwenden Sie das Standard-/health ohne ?deep.

Auth: Erforderlich bei Non-Loopback-Binds und wenn Loopback mit --require-auth gehärtet ist. Bei einem gewöhnlichen Loopback-Bind (127.0.0.0/8, localhost, ::1, [::1]) wird /health vor dem Bearer-Middleware registriert, damit k8s/Compose-Probes innerhalb des Pods das Token nicht übertragen müssen. Bei Non-Loopback (--hostname 0.0.0.0 usw.) oder gehärtetem Loopback wird die Route nach der Bearer-Middleware registriert und gibt 401 ohne gültiges Token zurück — andernfalls könnte ein nicht authentifizierter Aufrufer beliebige Adressen abtasten, um zu bestätigen, dass ein qwen serve existiert, ein Info-Leak mit geringer Schweregrad, der sich schlecht mit Port-Scanning kombinieren lässt. CORS-Deny + Host-Allowlist gelten weiterhin für die gewöhnliche Loopback-Ausnahme.

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

Diese authentifizierten Routen verwalten die Qwen Code-Installation des Daemons, unabhängig vom ausgewählten Workspace. Sie verwenden immer REST, auch von SDK-Clients mit einem ACP-Sitzungstransport. Die daemon_update-Funktion bewirbt das Protokoll; die Verfügbarkeit wird durch den zurückgegebenen Zustand bestimmt.

GET prüft auf Releases, ohne sie herunterzuladen oder zu aktivieren. Erfolgreiche Prüfungen werden 15 Minuten lang gecacht, Fehler eine Minute lang; ?refresh=true fordert eine neue Prüfung an. Gleichzeitige Prüfungen teilen sich eine Suche. Die Antwort enthält state (available, up-to-date, installing, ready, restarting, unavailable oder error), canInstall, optionale currentVersion und latestVersion sowie optionale instructions und message. currentVersion identifiziert den laufenden Daemon, auch nachdem ein Update vorbereitet wurde. Nicht unterstützte Installationsmethoden können available mit canInstall: false und manuellen Anweisungen melden.

Automatische Updates erfordern einen echten CLI-Lebenszyklus mit POSIX process.execve, eine Standalone-Installation oder eine globale npm/pnpm/yarn/bun-Installation, die den veröffentlichten Launcher ausführt (ein root-besitzener npm-Prefix ist enthalten, da das Staging niemals in den globalen Prefix schreibt), und Betreiber-Einstellungen, die general.enableAutoUpdate erlauben. Eingebettete Server, Windows, nicht unterstützte Node-Runtimes und der Entwicklungsmodus melden unavailable. Nur globale/Systemeinstellungen gelten; Workspace-Einstellungen können die Installation nicht aktivieren. Die Verbindung muss den primären Listener und sein Daemon-Laufzeit-Token verwenden oder die explizit vertrauenswürdige Loopback-Bereitstellung ohne Token. Gekoppelte Browser und Local-Control-Verbindungen melden unavailable, da ihre Anmeldedaten oder ihr Listener einen Neustart nicht überleben würden; ihre Update-Mutationen geben 403 update_connection_unsupported zurück.

Beide POST-Routen erfordern die Betreiber-Autorität des strengen Mutations-Gates für den Daemon und akzeptieren keine Parameter. Der Server wählt Release, Ziel und Launcher aus; Clients können keine Version oder keinen Befehl angeben.

• POST /daemon/update/prepare startet einen Hintergrund-Download und gibt 202 mit state: "installing" zurück. Es ändert die aktive Installation nicht. Poll GET, bis der Zustand ready ist; wiederholte Vorbereitungen teilen sich denselben Vorgang, und ein vorbereitetes Update gibt 200 zurück. Wenn kein automatisches Update verfügbar ist, gibt es 409 update_unavailable zurück.
• POST /daemon/update/restart erfordert ein vorbereitetes Update, andernfalls gibt es 409 update_not_ready zurück. Es antwortet mit 202 und state: "restarting" vor der Aktivierung des Updates, schließt den Daemon ordnungsgemäß und ersetzt den Prozess durch den aktualisierten Launcher. Wiederholte Klicks teilen sich einen Neustart. Nach der Antwort löst der Daemon das aktuelle Release einmal neu auf: Wenn es neuer als das vorbereitete ist und One-Click es abdeckt, wird das neuere Release gestaged und die vorbereitete Nutzlast verworfen, sodass ein langlebiger Daemon beim aktuellen neuesten Stand landet und nicht bei dem, was zum Zeitpunkt der ersten Vorbereitung aktuell war. Die neuere Nutzlast wird committet, bevor die ersetzte verworfen wird, und dieses Verwerfen erfolgt best-effort: Ein fehlgeschlagenes Verwerfen leckt Festplattenspeicher, hinterlässt aber nie die neuere Nutzlast als Waise oder fällt auf eine zurück, die möglicherweise halb entfernt ist. latestVersion meldet dann das neuere Ziel, während state auf restarting bleibt. Eine fehlgeschlagene Neuauswertung oder das Staging wendet stattdessen das vorbereitete Release an; der Klick wird durch einen Registry-Fehler nie auf der laufenden Version festgehalten. Der Ersatz behält PID, Arbeitsverzeichnis, CLI-Optionen, gebundenen Port und effektives Daemon-Token bei, löscht alte Versions-Pins und öffnet keinen Browser erneut. Der Client pollt GET, bis sich currentVersion ändert, und lädt dann das Dokument unter der URL neu, die bei der Anforderung des Updates erfasst wurde. Da das Staging nach dem 202 läuft und Minuten dauern kann, misst der Client seine Neustart-Frist anhand kontinuierlicher Unerreichbarkeit, nicht anhand des Klicks: Ein Daemon, der weiterhin antwortet, arbeitet noch. Eine großzügige absolute Obergrenze (20 Minuten) fängt einen Daemon ab, der erreichbar bleibt, aber restarting nie verlässt. Sie liegt über der gesamten Staging-Kette, nicht über einer einzelnen Timeout-Konstante: Ein Standalone-Archiv-Download versucht OSS und dann GitHub sequenziell mit einem Budget von jeweils fünf Minuten, und die Abrufe der Prüfsumme und Signatur addieren zwei weitere Minuten, sodass ein Restaging etwa zwölf Minuten für Download und Überprüfung vor der Aktivierung verbrauchen kann; das verwaltete npm-Kindprozess ist auf zehn Minuten begrenzt. Jeder Aufgabepfad hält einen wiederholbaren Eintrag auf dem Bildschirm, weil ein blockierter Daemon weiterhin restarting meldet, was die Steuerung sonst nicht anzeigt. Sobald der Neustart bestätigt ist, bleibt restarting haften, bis der Prozess ersetzt ist, sodass ein erreichbarer Daemon, der einen anderen Zustand mit unverändertem currentVersion meldet, bedeutet, dass der Ersatz nicht auf dem neuen Build gelandet ist; der Client stoppt das Warten, veröffentlicht diesen festen Zustand und meldet einen Fehler, anstatt ewig auf eine Versionsänderung zu warten. Diese Prüfung gilt nur für ein initiiertes Polling nach der Bestätigung: Status- und Neustart-Anfragen sind unabhängig, sodass ein früher gestartetes Polling danach einen Snapshot vor dem Neustart liefern kann, und das Lesen als fester Daemon würde einen falschen Fehler melden und das Neuladen unterdrücken, das ein erfolgreiches Update dem Benutzer noch schuldet. Die Validierung des Standalone-Launchers läuft vor dem Schließen der Dienste; eine fehlgeschlagene Prüfung lässt den Daemon laufen. Fehler nach Beginn des Herunterfahrens oder während des Prozessersatzes sind nicht garantiert wiederherstellbar.

Web Shell prüft und bereitet verfügbare unterstützte Updates automatisch im Hintergrund vor und zeigt seine versionsnahe Update-Schaltfläche an, wenn ein vorbereitetes Update bereit ist oder wenn ein verfügbares Update manuelle Anweisungen enthält. Im Zustand der manuellen Anweisungen öffnet die Schaltfläche ein Popover mit den Anweisungen aus der Prüfung und bereitet oder startet niemals neu. Vorbereitung und Bereitschaft überstehen Neuladungen der Workspace-Laufzeitumgebung. Ein vorbereitetes Update legt sein Ziel fest: Das Polling-GET, einschließlich ?refresh=true, meldet weiterhin das vorbereitete latestVersion und lädt niemals erneut herunter, sodass ein Daemon, der über mehrere Releases hinweg aktiv bleibt, keine Downloads im Hintergrund verschlingt. Nur der Neustart löst das Ziel erneut auf. Ein normales Herunterfahren des Daemons verwirft den vorbereiteten Download. Aktivierungsfehler halten den Daemon am Laufen und melden error; die nächste Prüfung nach Ablauf der einminütigen Fehler-Cache kann einen neuen Download für den Wiederholungsversuch vorbereiten. Das Deaktivieren automatischer Updates entfernt die Bereitschaft und räumt den Download auf, bevor ein Neustart beginnen kann. Sobald ein Neustart läuft, wird er nicht gestört: Während sich der Status in restarting befindet, geben Status-, Prepare- und Restart-Routen zurück, ohne die Operator-Einstellung zu konsultieren, und die Aufräumaktion beim Herunterfahren ist eine No-Op-Aktion, sodass ein Restaging, das Minuten dauert, nicht seinen Payload entzogen bekommen kann. Das Klicken auf die Schaltfläche im Ready-Zustand startet den gesamten Daemon explizit neu und unterbricht dessen aktive Sitzungen.

GET /daemon/status

Schreibgeschützte Operator-Diagnose. Im Gegensatz zu /health ist dies eine normale Daemon-API: Sie wird nach Bearer-Authentifizierung und Ratenbegrenzung registriert, auch bei Loopback-Binds. Abfrageparameter:

• detail=summary (Standard) liest nur den In-Memory-Daemon-Status.
• detail=full enthält außerdem Live-Sitzungsdiagnosen, ACP-Verbindungsdiagnosen, Auth-Gerätefluss-Zählungen und Workspace-Statusabschnitte.
• Jedes andere detail gibt 400 { "code": "invalid_detail" } zurück.

summary fragt absichtlich keine Workspace-Statusmethoden ab, startet kein ACP-Kind und erzeugt keine Sitzung. full fragt jeden Workspace-Abschnitt unabhängig voneinander ab; ein Timeout oder eine Ausnahme markiert nur diesen Abschnitt als unavailable und fügt ein workspace_status_unavailable-Problem hinzu.

Antwortformat:

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

Multi-Workspace-Antworten enthalten auch oberste workspaces[]-Zeilen mit { id, cwd, displayName?, primary, trusted }. Der optionale Anzeigename wird weggelassen, wenn er nicht gesetzt ist, und bleibt rein presentationsbezogen; Statusverbraucher müssen weiterhin id oder cwd verwenden, um Laufzeitumgebungen zu korrelieren.

runtime.perf ist optional. Wenn vorhanden, meldet es nur Event-Loop-Lag des Daemon-Prozesses, Prompt-FIFO-Warteschlangen-Wartezeit-Stichproben und Daemon-Kind-Pipe-Byte-Zähler; ACP-Kind-Event-Loop-Lag ist in /daemon/status nicht enthalten.

status ist error, wenn irgendein Problem eine Fehler-Schwere hat, warning, wenn irgendein Problem eine Warnungs-Schwere hat, andernfalls ok. Problemcodes sind stabil und umfassen 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 und workspace_status_unavailable. Im kurzen Zeitfenster, nachdem der Listener bereit ist, aber bevor die vollständige Laufzeitumgebung gemountet wurde, kann /daemon/status daemon_runtime_starting melden; wenn das asynchrone Mounten der Laufzeitumgebung fehlschlägt, meldet es daemon_runtime_failed, während Nicht-Status-Laufzeitumgebungs-Routen 503 zurückgeben.

runtime.activity meldet die Prompt-Aktivität auf Daemon-Ebene. activePrompts zählt Sitzungen mit einem laufenden Prompt. pendingPrompts zählt alle akzeptierten Prompts, die noch nicht abgeschlossen sind, einschließlich des laufenden Prompts und der im FIFO-Modus wartenden Prompts. queuedPrompts zählt die im FIFO-Modus wartenden Prompts, die akzeptiert, aber noch nicht dispatcht wurden. lastActivityAt ist der ISO 8601-Zeitstempel des letzten Prompt-Starts/-Endes oder der letzten Sitzungserstellung; null, wenn der Daemon seit dem Start keine Aktivität verarbeitet hat. idleSinceMs wird zum Zeitpunkt der Antwortgenerierung aus lastActivityAt berechnet.

limits.memory ist additiv und meldet die aufgelösten Speicherwerte des Daemons: ein erforderliches enforced: false, ein childHeap-Objekt (mode: off, observe oder admit; admissionEnforced, wahr nur für verwaltete admit; maxConcurrentChildren und perChildCeilingMb, beide null unter mode: 'off', was nichts modelliert — und perChildCeilingMb zusätzlich null, wo innerhalb von modeled.minChildHeapMb keine Partition modelliert werden kann — entweder kann der Pool ein Kind auf dieser Untergrenze nicht abdecken, oder die Obergrenze würde darunter fallen, wenn sie bei modeled.legacyChildCeilingMb gedeckelt wird, was floor(available / 2) ist und daher auf einem Host unter 1024 MB unter die Untergrenze fällt. Es ist niemals 0, und maxConcurrentChildren ist in diesen Fällen 0, da ein Host, der keine Partition modelliert, eine berechnete Antwort ist und kein fehlendes Modell; und refusals, die Starts, die das modellierte Limit überschritten hätten), configuredBudgetMb, effectiveBudgetMb (der konfigurierte Wert, gedeckelt durch den aufgelösten cgroup/Host-Speicher), budgetSource (flag / derived), availableMemoryMb, availableMemorySource (constrained / host), insufficientMemory und ein modeled-Objekt mit rootReserveMb, childPoolMb, minChildHeapMb, maxChildHeapMb und legacyChildCeilingMb (ein konservatives Modell der Obergrenze, die ein ACP-Kind heute erhält, die unter dem tatsächlichen Wert liegen kann). runtime.memory meldet zusätzlich registeredWorkspaces (die Registrierungsanzahl — nicht entfernte Workspace-Einträge, einschließlich drainender, übergehender oder blockierter Einträge; keine Live-Kind-Anzahl), activeAcpChildren (Daemon-verwaltete ACP-Kinder mit einem aktiven, nicht sterbenden Kanal — schließt Übergangs- oder Blockierteinträge ein, aber schließt einen Workspace aus, dessen Kill gestartet wurde, auch wenn das Kind noch nicht beendet ist; keine Kanal-Worker, MCP-Nachfahren oder nicht zugeordnete Reservierungen), childRssCoverage (active_children — jedes ACP-Kind mit einem aktiven Kanal, was die Menge ist, die activeAcpChildren zählt; ältere Daemons senden primary_only), ein unten beschriebenes children-Objekt und ein modeled-Objekt mit recommendedShareAtRegisteredMb (null, wenn kein Workspace registriert ist) und recommendedShareAtActiveMb (null, wenn kein Kind aktiv ist). Jeder Anteil ist auf die Legacy-Kind-Obergrenze gedeckelt und nur dann auf die minimale Kind-Heap-Untergrenze festgelegt, wenn die Obergrenze dies zulässt — auf einem kleinen Host liegt die Obergrenze unter der Untergrenze, sodass Anteil × Anzahl den Kind-Pool überschreiten kann. Lesen Sie einen Anteil als Empfehlung, nicht als Partition des Pools. Die Größe des Kind-Heaps bleibt empfehlend: Kein Argument beim Kind-Start leitet sich aus diesen Werten ab. Opt-in admit erzwingt die modellierte Anzahl gleichzeitiger Kinder, während das Standardverhalten observe nur hypothetische Ablehnungen protokolliert. runtime.memory.committedAcpChildren zählt verwaltete ACP-Reservierungen und angehängte Kinder, einschließlich beendender Kinder bis zur Registrierungsfreigabe; es ist null, wenn die verwaltete Registrierung nicht verfügbar ist. childHeap modelliert eine feste Partition von modeled.childPoolMb — jedes Kind würde denselben perChildCeilingMb erhalten, sodass die modellierte Gesamtmenge innerhalb des Pools bleibt, anstatt sich wie ein pro-Start-Anteil anzusammeln. Lesen Sie refusals nur als Zulassungsdruck: Eine Anzahl von 0 bedeutet nicht, dass die Partition sicher angewendet werden kann, da Kinder auf der viel größeren hostabgeleiteten Obergrenze laufen, sodass eine Arbeitslast, die mehr alten Speicherplatz benötigt als perChildCeilingMb, hier gesund ist und erst fehlschlagen würde, wenn die Partition angewendet würde. Zwei weitere Gründe, warum eine ungleich Null Anzahl nicht unbedingt Kapazitätsdruck bedeutet: Die Zulassungsentscheidung zählt ein beendendes Kind, bis es beendet ist, sodass bei einem Daemon, der bereits maxConcurrentChildren erreicht hat, jeder Kanalersatz während des Überlappungsfensters eine Ablehnung bucht; und auf einem Host, der zu klein ist, um eine Partition zu modellieren, ist maxConcurrentChildren 0, sodass refusals der gesamten ACP-Startanzahl entspricht, wobei insufficientMemory das Feld ist, das dies erklärt. In admit schlägt ein Modell mit null Slots den Start fehl. Ein vollständig verwalteter Daemon, der vor einer Erschöpfung der Kapazität steht, kann ein am längsten nicht verwendetes leeres ACP ohne aktive Sitzungen oder ausstehende Arbeiten zurückfordern, auf die verfolgte Freigabe warten und dann die Zulassung einmal erneut versuchen, bevor er startet. Geladene Sitzungen bleiben geschützt; Workspace-Registrierung und gespeicherter Verlauf bleiben erhalten. Der Zähler refusals zählt abgelehnte Zulassungsversuche, einschließlich einer anfänglichen Ablehnung, gefolgt von einer erfolgreichen Rückforderung, nicht endgültige benutzersichtbare Fehler. Erschöpfte Kapazität gibt REST HTTP 503 mit code: "acp_child_capacity_exhausted", maxConcurrentChildren und committedAcpChildren zurück (ohne die abgelehnte Reservierung), ohne Retry-After. ACP JSON-RPC verwendet -32603 mit data.errorKind, der diesen Code trägt, data.httpStatus: 503 und dieselben Zähler. Ein verifizierter Standalone-Erstellungs-Rollback vor dem Dispatch behält standalone_creation_rolled_back, seine Sitzungs-ID und Wiederholbarkeit bei und verschachtelt den Kapazitätscode und die Zähler unter capacity; unsichere Erstellungsergebnisse behalten ihre bestehenden Wiederherstellungssemantiken bei. Clients sollten automatische Kapazitätswiederholungen stoppen und den Entwurf oder die ausgewählte Sitzung für manuelle Wiederholungen beibehalten. Auf dem normalen Pfad runQwenServe wird das Budget aufgelöst, bevor die Bootstrap-App erstellt wird, sodass limits.memory während des Bootstrap-Fensters bereits gefüllt ist. Es ist nur auf Pfaden null, die kein Budget auflösen (wie Direct-Embed, das runQwenServeImpl umgeht). Der SDK-Typ erlaubt null, sodass korrekte Clients damit umgehen können.

runtime.memory.children ist innerhalb dieses Blocks additiv und meldet die aggregierte RSS über die Kinder, die childRssCoverage nennt: rssBytes (deren summierte selbst gemeldete RSS), sampled (wie viele einen Messwert geliefert haben) und oldestReadingAgeMs (das Alter der ältesten Messung in der Summe, damit ein Aufrufer erkennen kann, wie weit auseinander ihre Teile aufgenommen wurden). Der Nenner für sampled ist das Geschwisterfeld activeAcpChildren, nicht wiederholt im Block; wenn sampled niedriger ist, ist rssBytes eine Untergrenze statt einer Gesamtsumme. Das Sampling ist an einen aktiven SSE/WS-Watcher gebunden, sodass eine Statusanfrage an einen Daemon, von dem niemand streamt, sampled: 0 meldet, selbst wenn lebende Kinder vorhanden sind — activeAcpChildren daneben macht diese Lücke sichtbar, und rssBytes: 0 mit sampled: 0 bedeutet nie einen gemessenen Wert von null. oldestReadingAgeMs ist null, wenn nichts gesampelt wurde und auch, wenn jeder Beitragende eine Bridge ist, die vor diesem Feld existierte, sodass es nie “aktuell” bedeutet. Lesen Sie die Summe gleichzeitig als Überzählung und Unterzählung: Die Summierung der prozessweisen RSS doppelt gezählt Seiten, die sich die Kinder teilen, während jedes Kind nur seinen eigenen Prozess meldet, sodass seine MCP-Nachfahren und jeder Kanal-Worker fehlen. Es ist nicht der Speicher des Daemon-Baums. Das Feld ist im SDK-Mirror optional, da Daemons, die primary_only melden, es nie senden.

runtime.memory.children.heap ist innerhalb dieses Blocks additiv und meldet die lebenszeitbezogenen Höchststände der V8-Alten-Generation jedes ACP-Kindes, aggregiert als Maximum, nicht als Summe: peakOldGenerationBytes, peakLiveSetBytes, peakTotalHeapBytes, majorGcCount, majorGcMs, unclassifiedSpaceNames und reported. Eine Heap-Obergrenze gilt pro Kind, und die Spitzen wurden zu unterschiedlichen Zeiten erreicht, daher würde eine Gesamtsumme keine Frage beantworten; jedes Feld ist ein unabhängiges Maximum über die meldenden Kinder hinweg, kein Porträt eines einzelnen Kindes, und eine Obergrenze pro Kind wird gegen jede Achse für sich beurteilt. reported zählt, wie viele von sampled beigetragen haben, und ist niedriger, wenn einige Kinder vor den Feldern existierten. Jede Byteangabe deckt die Alte Generation ab — was --max-old-space-size tatsächlich begrenzt — und nicht nur old_space, da ein Kind seine Obergrenze erschöpfen kann, während old_space bei wenigen Megabytes liegt und large_object_space alles enthält. peakOldGenerationBytes sind committete Bytes und steigen mit der dem Kind zugewiesenen Obergrenze, lesen Sie es daher als obere Grenze dessen, was die Workload benötigt, nicht als deren Anforderung; peakLiveSetBytes ist das, was einen Major-GC überlebt und sich nicht mit der Obergrenze bewegt, was es zur Zahl macht, die aussagen kann, dass ein Kind nicht hineinpasst; lesen Sie es als obere Grenze statt als exakten Live-Satz, da GC-Einträge asynchron eintreffen und alles, was zwischen der Bereinigung und dem Lesen allokiert wurde, gezählt wird. peakLiveSetBytes ist 0 bis ein Major-GC beobachtet wird, was eine Abwesenheit ist, keine Messung. unclassifiedSpaceNames ist die Vereinigungsmenge der Heap-Räume, die kein meldendes Kind klassifizieren konnte; V8 benennt Räume zwischen Versionen um und fügt neue hinzu, ein unbekannter Raum wird aus den Summen entfernt, und das Entfernen führt zu einer Unterzählung — ein nicht-leeres Array bedeutet also, dass die Byteangaben unvollständig sind und nicht als vollständige Messung gelesen werden dürfen. Das gesamte Objekt ist null, niemals ein auf Null gesetztes Objekt, wenn kein stichprobenartig erfasstes Kind eines gemeldet hat; ohne angehängten SSE/WS-Watcher wird gar nichts stichprobenartig erfasst, dies ist also ein Routinezustand, kein Randfall. Alles davon ist beobachtend: Hier wird nichts dimensioniert, keine Spawn-Aktion verweigert oder limits.memory.enforced von false verschoben.

runtime.memory.pressure ist innerhalb dieses Blocks additiv und meldet den eigenen Speicherdruck des Daemon-Roots: mode (off / observe), level (normal / soft / hard / critical), source (rss / heap / unknown), ratio sowie die sechs Rohwerte, aus denen die Verhältnisse stammen — rssBytes, rssRatio, availableBytes, heapUsedBytes, heapRatio, heapLimitBytes. ratio ist der größere Wert von rssRatio und heapRatio, und source gibt an, welcher es war; Gleichstände werden als rss gemeldet. availableBytes ist limits.memory.availableMemoryMb in Bytes — absichtlich der erkannte cgroup-/Host-Wert statt effectiveBudgetMb, denn was den Prozess beendet, ist das reale Limit, nicht die Policy-Zahl des Operators. source: "unknown" bedeutet, dass weder Nenner messbar war, und darf nicht als gesund interpretiert werden; level ist in diesem Fall nur deshalb normal, weil es nichts zu klassifizieren gibt. Die Werte decken nur den Daemon-Root-Prozess ab: Es sind die eigenen memoryUsage() dieses Prozesses, sodass wachsende Kinder sie nicht verschieben. runtime.memory.children meldet diese separat, und keiner der Werte ist Prozessbaum-Speicher. Beide Modi melden den gesamten Block; nur observe hebt zusätzlich die pfadfreie daemon_memory_pressure-Warnung in das Status-Rollup, sodass off das oberste status unverändert lässt. In keinem Modus wird remediiert. Das Feld ist im SDK-Mirror optional, da Daemons, die runtime.memory vor seiner Existenz ausgeliefert haben, den Block ohne es senden.

limits.maxRegisteredWorkspaces ist additiv und meldet das aufgelöste Cap für Benutzerregistrierungen (Standard 256, konfigurierbar von 1 bis 256). limits.maxChannelControlWorkspaces meldet das unabhängige Cap für Control-/Recovery-Owner von 25 beim Standard-Daemon, auch wenn Kanäle deaktiviert sind. Custom-Controller werben dieses Feld nur an, wenn sie es durchsetzen. Diese Felder sind sowohl in Bootstrap- als auch in Ready-Antworten vorhanden; ältere Daemons können sie weglassen. Der Kanal-Controller lehnt Übergangs-Owner-Vereinigungsmengen über seinem Cap mit 409 channel_control_workspace_limit_reached ab, bevor Kandidaten-Worker konstruiert werden; eine anfängliche Boot-Zeit-Vereinigungsmenge über dem Cap lässt den Start fehlschlagen, bevor der Listener veröffentlicht wird, hat also keine HTTP-Oberfläche. Die Registrierungskapazität bestimmt nicht den SDK-Kanal-Timeout.

limits.maxTotalSessions ist additiv. null bedeutet, dass das effektive daemonweite Cap für frische Sitzungen deaktiviert ist. Wenn die aufgelöste Registrierungskapazität (Standard 256, konfigurierbar über QWEN_SERVE_MAX_WORKSPACES oder eingebettetes maxRegisteredWorkspaces) 25 überschreitet und --max-total-sessions weggelassen wird, verwendet der Standard-Daemon eine feste Gesamtzahl von 800, selbst bei einem Startup-Workspace. Bei Registrierungskapazitäten von 25 oder weniger leiten mehrere Startup-/Wiederherstellungs-Workspaces mit endlichem maxSessionsPerWorkspace die effektive Gesamtzahl einmalig als maxSessionsPerWorkspace * workspaceCount über derselben Anzahl aus Startup plus Wiederherstellung ab; ein einzelner Startup- oder Wiederherstellungs-Workspace behält ein unbegrenztes Standardverhalten. Explizite Gesamtlimits, einschließlich deaktivierter Werte, haben Vorrang. Spätere dynamische Registrierungen berechnen die Gesamtzahl nicht neu. Direkte createServeApp-Einbettungen müssen ihre eigene gemeinsame Zulassungsrichtlinie bereitstellen. Wenn gesetzt, begrenzt es die Erstellung frischer Sitzungen daemonweit und meldet Fehler aufgrund von Gesamtlimits mit dem bestehenden session_limit_exceeded-Fehlerformat plus scope: "total".

runtime.channel.live meldet den ACP-Bridge-Kanal innerhalb des Daemons. Es ist nicht der Kanal-Adapter-Worker. Daemon-verwaltete Kanäle nutzen runtime.channelWorker, dessen state eines von disabled, starting, running, exited, failed oder stopped ist. Wenn ein Worker running erreicht und dann beendet wird, hält /daemon/status den Daemon online und meldet den Warnungs-Problemcode channel_worker_exited.

Der Start von Daemon-verwalteten Kanal-Workern durch eine explizite qwen serve --channel ... bleibt Fail-Fast und hat Vorrang vor persistierten Starteinstellungen. Ein Boot ohne Flag stellt serve.channels aus jedem vertrauenswürdigen registrierten Workspace wieder her, wobei jeder die Liste in seinen eigenen Workspace-scope-Einstellungen beisteuert. Die wiederhergestellten Namen bilden eine Auswahl, deren Besitzer wie üblich aufgelöst werden, wobei der Workspace, der einen Namen aufgelistet hat, einen sonst mehrdeutigen Besitzerkonflikt bricht. Diese Boot-Zuordnung besteht so lange, wie der Daemon läuft: Ein PUT /workspace/channel, das einen solchen Namen wieder aktiviert, löst ihn so auf, wie es beim Boot geschah, selbst nachdem die Auswahl dazwischen gestoppt wurde. Ein Name, den ein Nicht-Primär-Workspace beigesteuert hat, wird verworfen, mit einem Log, der ihn identifiziert, wenn er nicht aufgelöst werden kann, damit ein veralteter Eintrag eines Workspaces die anderen nicht blockiert; ein Name, den der Primär-Workspace aufgelistet hat, lässt die gesamte Wiederherstellung scheitern, unabhängig davon, ob ein anderer Workspace ihn ebenfalls auflistet. all bleibt primär-only: Es wird ignoriert und anderswo gemeldet.

Ein vertrauenswürdiger Nicht-Primär-Workspace, der nach dem Boot registriert wird, stellt auch sein eigenes serve.channels wieder her, indem er die Kanal-Laufzeitumgebung lädt und das Kanal-Service-Lease reserviert, falls nichts anderes dies getan hat. Diese Wiederherstellung:

• geschieht einmal pro Daemon-Lauf — aufgezeichnet, sobald der Workspace irgendetwas anfordert — sodass eine spätere Entfernung und erneute Registrierung oder eine Neu-Materialisierung des Vertrauens nicht rückgängig macht, was ein Operator getan hat, der einen dieser Kanäle dazwischen gestoppt hat;
• geschieht nicht unter einer expliziten --channel-Auswahl, die kein später registrierter Workspace erweitert;
• geschieht nicht, nachdem DELETE /workspace/channel das Hosting eingestellt hat, bis ein PUT /workspace/channel eine Auswahl erneut bestätigt oder der Daemon neu gestartet wird;
• lässt eine bestätigte all-Auswahl unverändert;
• fügt die Namen dieses Workspaces in einer Änderung der bestätigten Auswahl hinzu, wobei jeweils nur eine späte Wiederherstellung durchgeführt wird. Im Gegensatz zum Startvorgang, bei dem ein nicht hostbarer Name verworfen und der Rest beibehalten wird, führt ein nicht zuordenbarer Name dazu, dass die gesamte Liste des Workspaces nicht wiederhergestellt wird, wobei der Fehler protokolliert und wie unten beschrieben gemeldet wird.

Die Registrierung wartet überhaupt nicht auf die Kanalsteuerung. Die Wiederherstellung wird in der Spur für die Kanalsteuerung eingereiht und die Antwort geschrieben, ohne darauf zu warten; dasselbe gilt für den Abgleich, der durch eine Registrierung oder Vertrauensänderung für Kanäle ausgelöst wird, die der Daemon bereits hostet. Ein Worker, der nie bereit wird, verzögert daher nur die dahinter eingereihte Kanalarbeit, niemals eine andere Registrierung oder einen Vertrauensabgleich. Die Kehrseite ist, dass ein 201 von POST /workspaces nicht bedeutet, dass die Kanäle dieses Workspaces aktiv sind oder dass ein bereits gehosteter Kanal, der ihm gehört, seinen Neustart abgeschlossen hat; lesen Sie GET /workspace/channel für weitere Informationen.

Ohne explizite Auswahl, eine serve.channels-Wiederherstellung beim Start oder eine Registrierung wie oben bleibt das Laden der Kanal-Laufzeit lazy (verzögert).

Gespeicherte Startnamen dürfen nicht leer sein, keinen führenden oder abschließenden Leerzeichen enthalten und keine unsicheren Steuer- oder unsichtbaren Zeichen enthalten. Ungültige Einträge werden einzeln übersprungen und anhand des Array-Index protokolliert; der Startvorgang trimmt sie nicht in andere Instanzennamen um und schreibt Einstellungen nicht neu. Worker-Argumente verwenden --channel=<value>, wobei ein führendes Minuszeichen als Teil des Namens erhalten bleibt.

Ein ungültiges Startfeld oder ein Validierungs- oder Lease-Fehler vor dem Start der Worker überspringt die automatische Wiederherstellung, mit einem Log-Eintrag, der serve.channels identifiziert, während unrelated Einstellungen wirksam bleiben. Ein fehlgeschlagener Worker-Start erlaubt dem Daemon fortzufahren, nachdem die Bereinigung erfolgreich war. Globale Laufzeit-Start-Timeouts und unbestätigte Worker-Stops folgen dem bestehenden Pfad für Startfehler; der Lease bleibt gehalten, solange die Worker-Beendigung unbestätigt ist. Das Kanalmanagement meldet persistierte Starteinstellungen und tatsächlichen Laufzeitstatus.

Einige serve.channels-Namen, die der Daemon nicht hochgefahren hat, werden gemeldet statt nur protokolliert. Solch ein Name tritt nie der bestätigten Auswahl bei, sodass kein Worker-Snapshot ihn enthält. Drei Fälle werden gemeldet:

• eine konfigurierte Startauswahl, deren Worker nicht starten konnte, auf dem Startpfad, der den Daemon ohne seine Kanäle am Laufen hält;
• ein Name, den der Boot-Besitzauflöser während der Zuordnung zu einem Workspace verworfen hat, gemeldet gegen jeden Workspace, der ihn auflistete;
• jeder Name, der nach einer fehlgeschlagenen späten Registrierungswiederherstellung noch immer nicht gehostet wird.

Sie erscheinen an zwei Stellen:

• /daemon/status meldet eine channel_restore_failed-Warnung pro Workspace, wobei jeder Kanal mit seinem Fehler benannt wird. Dies ist die vollständige Oberfläche und ist auch in der Bootstrap-Antwort vorhanden, die die einzige ist, die existiert, während Boot-Aufzeichnungen geschrieben werden. Maximal 64 Kanäle werden pro Workspace benannt, jeder Name auf 128 Zeichen begrenzt, mit and <n> more wenn die Liste länger ist;
• die GET /workspaces/:workspace/channels dieses Workspaces listet den Kanal mit runtime: { state: "error", lastError } anstelle von stopped auf, wobei lastError der eigene Startfehler des Adapters ist, wenn der Worker einen für diesen Kanal gemeldet hat, andernfalls der Fehler des Versuchs. Diese Oberfläche wird aus dem eigenen Kanal-Einstellungsbereich des Workspaces aufgebaut, kann also nur einen Namen tragen, den dieser Bereich definiert – ein Name, den kein registrierter Workspace konfiguriert, oder einer, dessen Konfiguration in einem anderen Workspace liegt, hat hier keine Zeile und wird nur auf /daemon/status gemeldet.

Alles andere, was einen serve.channels-Namen ungehostet lässt, wird nur im Daemon-Log diagnostiziert: ein Name, der verloren ging, weil die gesamte Liste unlesbar oder ungültig war, eine Liste eines Nicht-Primär-Workspaces, die verworfen wurde, weil der Primäre all auswählte, eine späte Wiederherstellung, die übersprungen wurde, weil die bestätigte Auswahl all ist, und die Liste eines Remote-(SSH)-Workspaces. Prüfen Sie Daemon-Logs dafür.

Ein Bericht bleibt bestehen, bis der Kanal gehostet wird – von diesem Workspace oder durch eine spätere Wiederherstellung von einem anderen –, bis sein Workspace nicht mehr registriert ist oder bis ein Operator handelt: POST Start, Stop oder Neustart auf dem Kanal, PUT/DELETE /workspace/channels/:name oder ein PUT/DELETE /workspace/channel, der die Auswahl ändert. PUT /workspace/channels/:name/startup löscht ihn nicht: Es überschreibt serve.channels, ohne etwas über den fehlgeschlagenen Versuch zu sagen. Der Bericht wird im Speicher gehalten: Ein neu gestarteter Daemon stellt erneut wieder und meldet, was dieser Versuch getan hat. Der Fehlertext ist credential-redacted (Anmeldedaten entfernt) und begrenzt, so wie das Daemon-Log ihn rendert.

Nachdem ein Worker bereit erreicht hat, werden unerwartete Beendigungen vom Serve-Supervisor innerhalb einer begrenzten Richtlinie neu gestartet: bis zu 3 Neustartversuche in einem 5-Minuten-Fenster, mit Backoff von 1s, dann 5s, dann 15s. Der Worker sendet IPC-Heartbeats alle 15s; wenn kein Heartbeat für 45s beobachtet wird, behandelt der Supervisor den Worker als stale (veraltet), tötet ihn, protokolliert staleHeartbeatAt und nutzt denselben Neustartpfad.

runtime.channelWorker kann additive operative Felder enthalten: requestedChannels, pid, startedAt, exitCode, signal, error, restartCount, lastExitAt, lastRestartAt, nextRestartAt, lastHeartbeatAt, staleHeartbeatAt, startupFailures und startupFailuresTruncated. Jeder Startfehler weist channel, phase (derzeit connect), ein optionales vom Adapter bereitgestelltes code sowie eine durch Zugangsdaten geschützte message auf. Für die aktuelle Worker-Generation werden maximal 64 Fehler gespeichert; das Kürzungsflag zeigt an, dass weitere Fehler beobachtet wurden. code ist diagnostischer Natur und keine stabile adapterübergreifende Klassifizierung. restartCount ist die Anzahl der Neustartversuche, die dieser Serve-Prozess im gesamten Lebenszyklus unternommen hat; ein laufender Worker mit restartCount > 0 ist gesund, sofern kein anderes Problem vorliegt. Ein laufender Worker, dessen requestedChannels Namen enthält, die in channels fehlen, meldet channel_worker_partial_connect.

Bei einem Daemon mit mehreren Arbeitsbereichen (wiederholtes --workspace) enthält runtime zusätzlich channelWorkers[] – einen Eintrag pro besitzendem Arbeitsbereich, jeweils ein channelWorker-Snapshot, annotiert mit workspaceId, workspaceCwd und primary. channelWorker bleibt als Snapshot des primären Arbeitsbereichs zur Kompatibilität gefüllt. Daemons mit einem einzelnen Arbeitsbereich lassen channelWorkers[] weg.

Daemon-gesteuerte Kanalsteuerung

Die channel_control-Funktion bewirbt die Ressource für die Laufzeitauswahl. Die Ressource ist daemonweit gültig, obwohl ihr Kompatibilitätspfad das Singularpräfix /workspace verwendet. Laufzeitauswahlen werden nicht persistiert und ändern die Option --channel des Daemons beim Start nicht.

GET /workspace/channel gibt einen unveränderlichen Manager-Snapshot zurück:

{
  "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 ist null, wenn deaktiviert. pendingSelection ist nur während einer Mutation vorhanden. transition ist eines von idle, starting, reconciling, stopping oder rolling_back.

PUT /workspace/channel ist streng getornt und akzeptiert genau eine Auswahl:

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

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

Namen werden gekürzt und dedupliziert, ohne Sortierung; ein leeres Namensarray ist ungültig. all bleibt auf den primären Arbeitsbereich beschränkt. Eine Änderung von deaktiviert zu aktiviert gibt 201 zurück; ein idempotenter PUT oder eine Ersetzung gibt 200 zurück. Die Antwort ist { changed, replaced, partial, state }. Eine gleiche Auswahl hält gesunde Worker am Platz, stellt aber eine gleiche Auswahl wieder her, deren Worker gestoppt oder fehlgeschlagen ist.

DELETE /workspace/channel ist streng geregelt und idempotent. Es gibt { changed, state } zurück; ein erfolgreicher Zustand ist deaktiviert. POST /workspace/channel/reload ist ebenfalls streng geregelt, liest Einstellungen neu, löst Arbeitsbereichsgruppen erneut auf und erzwingt die Abstimmung der festgelegten Auswahl. Es gibt 409 channel_worker_not_enabled zurück, wenn deaktiviert. Die channel_reload-Funktion wird dynamisch nur dann beworben, wenn der Manager eine festgelegte, nachladbare Auswahl hat.

Jedes Aktivieren, Ersetzen, Nachladen, Stoppen und Herunterfahren des Daemons tritt in eine FIFO-Lifecycle-Spur ein. GET wartet nicht auf diese Spur. Arbeitsbereichsgruppen, deren geordnete Auswahl sich nicht geändert hat, bleiben online. Ersetzungsfehler versuchen, neu gestartete Worker zu stoppen und die vorherige festgelegte Auswahl wiederherzustellen. Clients müssen rolledBack, rollbackError und state prüfen, da auch Bereinigung oder Wiederherstellung fehlschlagen können. Der Daemon hält die PID-Lease des Kanal-Dienstes während einer Transaktion und gibt sie erst frei, wenn jeder relevante Kindprozess-Exit bestätigt wurde.

Stabile Steuerungsfehler sind:

• 400 invalid_channel_selection, channel_workspace_mismatch oder ambiguous_channel_workspace
• 403 untrusted_workspace
• 409 channel_service_conflict, channel_worker_not_enabled oder channel_control_workspace_limit_reached
• 500 channel_worker_stop_failed
• 502 channel_worker_start_failed mit rolledBack und einem optionalen zugangsdatenbereinigten rollbackError
• 503 daemon_draining

Strenge Schreibvorgänge von einer tokenlosen primären Anfrage, die das Gate ohne vertrauenswürdige Loopback-Autorität erreicht, geben 401 token_required zurück, bevor Steuerungscode ausgeführt wird. Fehlende oder ungültige konfigurierte Zugangsdaten und ungepaarte Local-Control-Zugangsdaten werden früher mit einfachem 401 Unauthorized abgelehnt. Vertrauenswürdige Loopback-primäre Anfragen werden normal ausgeführt. Sobald eine Anfrage beginnt, bricht das Trennen des HTTP-Clients die Lifecycle-Transaktion nicht ab; Clients können denselben PUT sicher wiederholen.

Für 502 channel_worker_start_failed kann die Antwort auch startupFailures[] und startupFailuresTruncated enthalten. Jeder Fehler fügt die vertrauenswürdige workspaceCwd des versuchten Workers hinzu. Diese Felder beschreiben die fehlgeschlagene Transaktion, während state den aktuellen Zustand nach dem Rollback beschreibt; ein späteres GET behält den fehlgeschlagenen Versuch nicht bei. Ein teilweise verbundener Worker gibt stattdessen Erfolg zurück und legt seine Fehler im Worker-Snapshot offen. Ein expliziter --channel-Start ohne verbundenen Adapter lässt den Start fehlschlagen. Ein aus Einstellungen abgeleiteter Startfehler wird protokolliert und erlaubt dem Daemon fortzufahren, nachdem die Bereinigung erfolgreich war, unterliegt jedoch dem globalen Timeout für den Laufzeitstart. Wenn die Bestätigung der Bereinigung fehlschlägt, bleibt das normale Verhalten bei Startfehlern und die Service-Lease erhalten.

qwen channel status ohne --daemon-url liest weiterhin Metadaten der Pidfile; mit --daemon-url liest es GET /workspace/channel. Während eines Neustartfensters bleibt die serve-eigene Pidfile reserviert, aber workerPid wird weggelassen, damit Clients keinen veralteten Worker-Prozess anzeigen. Bei einem Daemon mit mehreren Arbeitsbereichen trägt die Pidfile auch ein additives workers[]-Array (pro Arbeitsbereich workspaceId / workspaceCwd / channels / live workerPid), während das oberste Level channels (Vereinigungsmenge) und workerPid (primär) für ältere Leser gefüllt bleiben; Daemons mit einem einzelnen Arbeitsbereich behalten die ursprüngliche Form mit einem einzigen Worker bei. Stdout/Stderr des Workers werden in das Daemon-Log weitergeleitet, wobei Bearer-Tokens, sensible Worker-Umgebungswerte und Proxy-URL-Zugangsdaten geschwärzt werden.

Verwaltung von Workspace-Kanälen

Die channel_management-Funktion bewirbt arbeitsbereichsbezogene Kanal-Konfiguration und Laufzeitverwaltung. Die Singular-Routen /workspace zielen auf die primäre Laufzeit. /workspaces/:workspace löst die exakte registrierte, vertrauenswürdige Laufzeit auf und fällt niemals auf die primäre Laufzeit zurück.

Die schreibgeschützte Erkennung verwendet:

• 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 gibt das Event-Journal des aufgelösten Workspace-Kanals als { "events": [...], "truncated": boolean } mit Cache-Control: no-store zurück, plus ein optionales channelLinkMeta-Mitglied: eine Zuordnung vom Kanalinstanznamen zu nicht-geheimen Link-Metadaten (type und baseUrl, jeweils nur vorhanden, wenn als String konfiguriert, und für GitHub-Kanäle ein aufgelöstes webOrigin — der Web-UI-Ursprung, den Clients direkt konkatenieren sollten, anstatt ihn aus dem API-Stamm neu abzuleiten). Die Metadaten werden aus den zusammengeführten System-, Benutzer- und Workspace-Einstellungen aufgelöst, mit denen die Kanal-Worker laufen — die verwaltungsseitige Auflistung auf Scope-Ebene enthält keine Kanäle, die in einem anderen Scope konfiguriert sind — und gefiltert auf Kanäle, deren aufgelöstes cwd zum abgefragten Workspace gehört, sodass ein Workspace niemals die Kanal-Metadaten eines anderen Workspaces erhält. Es ermöglicht Clients, Journalzeilen zu verknüpfen (z. B. einen GitHub-PR- oder Issue-Verweis), auch für Kanäle, die von Benutzer- oder Systemeinstellungen geerbt wurden. Das Mitglied wird vollständig weggelassen, wenn kein Kanal aufgelöst wird, und ältere Daemons senden es nie; ein Fehler beim Lesen der Einstellungen führt dazu, dass es fehlt, statt das Lesen des Journals fehlschlagen zu lassen. Jedes Ereignis protokolliert, was ein Kanal getan hat — eine eingehende Nachricht, die er akzeptiert oder übersprungen hat (mit der maschinellen Begründung: reason_filter, mention_required, duplicate, eine Absender-Gate-Ablehnung, github_api_error), einen GitHub-Thread, dessen Verarbeitung fehlgeschlagen ist und den er erneut lesen wird (failed mit github_api_error: ein GitHub-Fehler oder ein lokaler Fehler, während der Kanal seinen eigenen Zustand nicht lesen oder schreiben kann oder eine der Thread-Aufgaben unvollständig ist), ein Veröffentlichungsergebnis, eine Übergangsaufgabe bei Eingang oder ein Polling-Ergebnis — und trägt niemals Nachrichtentext. Ein GitHub-Polling, das mehr als 20 Benachrichtigungen filtert, protokolliert die ersten 20 einzeln und eine weitere reason_filter-Zeile, deren detail.filtered den Rest zählt, damit ein angehefteter Polling-Cursor das Journal nicht mit Wiederholungen desselben Stapels überflutet. Während der Cursor gehalten wird, wird ein Kommentar, den das Polling erneut liest, einmal pro Fenster als duplicate oder mention_required protokolliert, und ein fehlschlagender Thread als github_api_error bei seinem ersten fehlgeschlagenen Polling im Fenster und bei jedem zehnten fehlgeschlagenen Polling (ein Ratenlimit- oder Anmeldeinformationsfehler: sein erstes und jedes zehnte Polling), sowie einmal, wenn er übersprungen wird. Die Zeilen, die einmal pro Fenster protokolliert werden, werden unter bis zu 8.192 Schlüsseln verfolgt; eine Zeile, deren Schlüssel nicht mehr passt, wird bei jedem Polling protokolliert. Abfrageparameter: limit (1-500, Standard 100), type (durch Komma getrennte inbound, outbound, task, poll), channel (den Parameter einmal pro Instanzname wiederholen) und since (ISO 8601). Die Route benötigt keine Betreiberberechtigung. Journal-Lesevorgänge sind asynchron und begrenzt: das aktuelle Journal plus eine rotierte Datei pro Kanal, 256 KiB pro Datei, 4 MiB pro Anfrage, 32 Dateien pro Anfrage, neueste zuerst. Link-Metadaten lesen zusätzlich synchron einen nebenwirkungsfreien Snapshot der zusammengeführten Einstellungen (ein paar kleine JSON-Dateien, aufgelöst gegen die effektive Umgebung der Laufzeitumgebung); es ist eine Best-Effort-Dekoration, daher lässt jeder Fehler das Mitglied weg, statt das Lesen des Journals fehlschlagen zu lassen. truncated ist wahr, wenn das Datensatzlimit oder eine Lesebegrenzung das Ergebnis beschnitten hat, einschließlich eines Journals, das höher ist als das Endfenster pro Datei. Ein Workspace ohne Journal gibt eine leere Liste zurück; ein Verzeichnis auf Scope-Ebene, das nicht gelesen werden kann, antwortet mit 5xx statt einer leeren Liste.

Der Katalog markiert die Typen, die von dieser Verwaltungs-API unterstützt werden, mit manageable: true. Instanz-Snapshots enthalten eine Revision, redigierte Geheimnis-Vorhandenseins-Metadaten, Startzustand und Laufzeitstatus; buchstäbliche Geheimnisse werden niemals zurückgegeben. Kanal-Snapshots verwenden Cache-Control: no-store.

Feldbeschreiber können verschachtelte Objekt-Metadaten über properties offenlegen. Numerische Beschreiber können exclusiveMinimum für eine offene Untergrenze und maximum für eine inklusive Obergrenze verwenden. Eine gespeicherte Zahl außerhalb einer neu deklarierten Grenze wird weiterhin akzeptiert, wenn der Client sie unverändert erneut sendet, sodass das Deklarieren einer Grenze keine unbeteiligten Bearbeitungen eines vorhandenen Kanals blockiert; ein Wert, den der Client tatsächlich geändert hat, muss beide Grenzen erfüllen. String- und Geheimnis-Beschreiber können multiline verwenden, um Clients nach einem mehrzeiligen Textbereich zu fragen; die Beschreibertypen erlauben dies nur bei Feldern auf oberster Ebene. Clients, die einen beworbenen Feldtyp nicht rendern, müssen seinen vorhandenen Konfigurationswert beibehalten, anstatt ihn zu erzwingen oder zu löschen, und ein Client, der ein multiline-Feld in einer einzeiligen Steuerung rendert, muss den gespeicherten Wert wortwörtlich beibehalten, anstatt seinen eingegebenen Wert ohne Zeilenumbrüche zurückzuschreiben. Objekt-Felder können nicht erforderlich sein, und verschachtelte Eigenschaften können keine Geheimnisse oder per Umgebungsvariablen auflösbare Felder sein; diese Verwaltungsprotokolle bleiben nur auf oberster Ebene. Eine verschachtelte required-Eigenschaft wird nur durchgesetzt, solange ihr Elternobjekt im Schreibvorgang vorhanden ist; das Weglassen des Elternobjekts lässt seine verschachtelten Anforderungen ungeprüft. Schreibvorgänge ersetzen den gespeicherten Wert jedes Felds vollständig, daher bedeutet das Beibehalten eines Objekts, das gespeicherte Objekt erneut zu senden; der Daemon führt keine Teilobjekte zusammen.

Konfigurationsschreibvorgänge verwenden optimistische Nebenläufigkeit und das strenge Gate für Betreiberberechtigungen:

• PUT /workspace/channels/:name
• DELETE /workspace/channels/:name
• PUT /workspace/channels/:name/startup
• die entsprechenden /workspaces/:workspace/...-Routen

Jede Einstellungsänderung enthält expectedRevision. Upsert-Anfragen enthalten ein config-Objekt und können explizite Geheimnisoperationen enthalten: preserve, replace oder clear. Eine Kanal-Konfiguration kann kein Arbeitsverzeichnis außerhalb des aufgelösten Workspaces auswählen.

Laufzeitaktionen sind streng geregelt POST-Anfragen an .../channels/:name/start, stop oder restart. Sie wirken nur auf den Worker, der dem aufgelösten Workspace gehört.

Das Pairing-Management ist nur für Instanzen verfügbar, die mit der pairing-Sender-Richtlinie oder Gruppen-Richtlinie konfiguriert sind:

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

Alle Pairing-Routen erfordern strenge Operator-Autorität und verwenden Cache-Control: no-store. Anfragen, Genehmigungen und Widerrufe sind auf die ausgewählte Channel-Instanz und den Workspace beschränkt. Ausstehende Anfragen enthalten einen typisierten Benutzer- oder Gruppen-Subjekt; Gruppenanfragen behalten auch den Absender bei, der die Anfrage initiiert hat. Genehmigungssnapshots enthalten senderIds und groupIds, da Allowlists keine Anzeigenamen speichern. Das Widerrufen eines unbekannten Benutzers oder einer Gruppe gibt 404 channel_pairing_approval_not_found zurück.

Kanal-Zustellung und Notify zurück

channel_delivery bewirbt sofortige, best-effort Zustellungsunterstützung. Es ist eine Protokollfähigkeit, kein Signal für die Worker-Gesundheit. Die Zustellung startet niemals einen fehlenden Worker, fällt nicht auf einen anderen Workspace zurück, wiederholt sich nicht, speichert keine Outbox und spielt keine historischen Benachrichtigungen nach.

Direktes Notify umgeht Agent und Session und wartet auf einen Sendeversuch:

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

Beide Routen verwenden das strenge Mutations-Gate. Die qualifizierte Route löst nur einen registrierten, vertrauenswürdigen Workspace auf. Erfolg ist 200 {delivered:true,deliveryId}. delivered:true bedeutet, dass das Channel-Send-Promise aufgelöst wurde; es beweist weder die Akzeptanz durch den Anbieter noch den Empfang durch den Benutzer oder eine Lesebestätigung. Anbieterspezifische Antwortvalidierung und konsistente Fehlergrund-Semantik über IM-Adapter hinweg liegen außerhalb dieses V1-Vertrags. Fehler sind 400 channel_delivery_invalid, 503 channel_worker_unavailable oder channel_delivery_queue_full, 504 channel_delivery_timeout sowie 502 channel_delivery_rejected oder channel_delivery_failed. Ein Timeout hat ein unbekanntes Ergebnis und wird nicht wiederholt. Es gibt absichtlich keinen separaten Konnektivitätstest-Endpunkt: Ein normaler Notify-Aufruf ist der End-to-End-Test.

Das wiedergebbare Ergebnis-Ereignis enthält nur Korrelation und bereinigten Status:

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

Ein leerer erfolgreicher Prompt-Final lässt Fehlerfelder aus:

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

source ist prompt oder scheduled; status ist delivered, failed oder skipped. skipped bedeutet, dass der berechtigte Turn erfolgreich abgeschlossen wurde, aber sein letzter Tool-freier Assistent-Antwortblock leer oder nur aus Leerzeichen bestand. Der Daemon verbraucht die Zustellungsautorisierung und veröffentlicht das Ereignis, ohne einen Channel-Worker aufzulösen. Die geplante Korrelation verwendet taskId und firedAt. Das Ereignis enthält niemals Ziel-IDs, Nachrichtentexte, Anmeldedaten oder Webhook-Geheimnisse.

Sicherheit: Die Antwort enthält niemals Bearer-Tokens, Client-IDs, vollständige ACP-Verbindungs-IDs, Device-Flow-Benutzer-Codes oder Verifizierungs-URLs. Beide Detailstufen können additive daemon.runId, daemon.logMode und daemon.logHealth enthalten. summary lässt den Daemon-Logpfad und Verlustdetails weg; full kann logPath, logIssues, logDroppedRecords und logDroppedBytes für authentifizierte Operatoren enthalten. Degradiertes Datei-Logging fügt dem normalen Status-Rollup die pfadfreie daemon_log_degraded-Warnung hinzu.

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

Stabiler Vertrag: Wenn v erhöht wird, hat sich das Frame-Layout auf eine rückwärtsinkompatible Weise geändert.

protocolVersions beschreibt die Serve-Protokollversionen, die der Daemon sprechen kann. current ist die bevorzugte Protokollversion des Daemons und supported ist die kompatible Menge. Clients, die ein spezifisches Protokoll erfordern, sollten supported prüfen; funktionsspezifische UI sollte weiterhin auf features zugreifen. Additiv zu v=1: Ältere v=1-Daemons lassen dieses Feld weg, daher sollten SDK-Clients, die auf ältere Builds abzielen, es als optional behandeln.

modelServices ist in Stage 1 immer []. Der Agent nutzt seinen einzelnen Standard-Modellservice und enumeriert ihn nicht über das Netzwerk. Stage 2 wird dies aus registrierten Modelladaptern befüllen, damit SDK-Clients Service-Auswahlmenüs erstellen können; bis dahin verlassen Sie sich NICHT darauf, dass dieses Feld nicht leer ist.

workspaceCwd ist der kanonische absolute Pfad für den primären Workspace des Daemons. Verwenden Sie ihn, um cwd bei POST /session wegzulassen (die Route fällt auf diesen primären Pfad zurück) und alte Einzel-Workspace-Clients kompatibel zu halten. Additiv zu v=1: Pre-§02 v=1-Daemons lassen das Feld weg — Clients, die auf ältere Builds abzielen, sollten vor der Verwendung null-checken.

workspaces[] listet jede registrierte Laufzeitumgebung auf. Neuere Einzel-Workspace-Daemons schließen die primäre Laufzeitumgebung ein, selbst wenn multi_workspace_sessions fehlt, damit Clients die stabile ID entdecken können, die von workspace-qualifizierten Routen benötigt wird; ältere Daemons können das Array weglassen. Jeder Eintrag ist { id, cwd, displayName?, primary, trusted, removable? }. displayName ist nur zur Darstellung gedacht und wird weggelassen, wenn nicht gesetzt. Der erste/primäre Workspace bleibt durch workspaceCwd gespiegelt; neue Clients wählen eine nicht-primäre Laufzeitumgebung, indem sie die cwd dieses Eintrags an POST /session übergeben. Nicht vertrauenswürdige Workspaces werden zur Diagnose angezeigt, lehnen aber die Erstellung neuer Sitzungen mit 403 untrusted_workspace ab, bis sich das Vertrauen ändert. removable ist bei Daemons vorhanden, die die Entfernung von Laufzeitumgebungen unterstützen, und ist nur für prozessdynamische oder wiederhergestellte sekundäre Laufzeitumgebungen wahr.

session_worktree_persistence_v1 bedeutet, dass der Daemon die Eigentümerschaft von Part 4A Worktrees persistieren und verifizieren kann. Erfolgreiche Antworten auf die Erstellung von Worktrees sowie Wiederherstellungsantworten, deren Kind entweder im Leerlauf verschoben wurde oder bereits den verifizierten Worktree-cwd meldet, tragen worktree Metadaten plus worktreeState: "persisted-v1". Eine Legacy-Best-Effort-Wiederherstellung oder eine Kaltwiederherstellung, deren Wiederherstellungsaufforderung ausgelöst statt geparkt wurde (suppressWorktreeContextRestore aus, sodass die Route die Bridge nach keiner Verschiebung fragte) und die daher eine aktive Aufforderung ohne aktuellen cwd meldet, kann immer noch worktree ohne diese Bescheinigung zurückgeben. Clients, die Isolation anfordern, müssen dieses Tag vorab prüfen und jede Antwort verifizieren; das worktree Objekt allein ist kein Nachweis für dauerhafte Eigentümerschaft.

session_worktree_reset_v1 bedeutet, dass der Daemon die Übertragung der Worktree-Eigentümerschaft unterstützt: POST /session/:id/worktree-reset verschiebt die Checkout-Eigentümerschaft einer persistierten Worktree-Sitzung auf eine frische Ersatzsitzung. Wiederherstellungsantworten erhalten drei typisierte 409-Klassifikationen neben diesem: worktree_session_superseded (die Sidecar der Sitzung trägt einen supersededBy Link — die Klassifikation wird allein aus diesem Link entschieden, bevor irgendein Marker gelesen wird, und der Link wird geschrieben, bevor der Marker kippt, daher ist der replacementSessionId im Body eine Weiterleitung zur Überprüfung, kein Beweis für Eigentümerschaft: In einem unterbrochenen Zustand vor dem Commit benennt er eine Sitzung, die nicht der Markerbesitzer ist, nicht selbst wiederhergestellt werden kann und vom wiederholten Reset eingesammelt wird), worktree_marker_missing (der Checkout-Marker fehlt; setzen Sie die Aufgabe zurück, um ihn neu zu erstellen — ein Wiederherstellungsversuch kann dies nicht, da kein Wiederherstellungspfad einen Marker schreibt), und worktree_reset_interrupted (eine vorherige Übertragung stürzte mitten im Flug ab, wobei ihre Sidecar-Links übereinstimmten; wiederholen Sie den Reset). Die unterbrochene Klassifikation wird zuerst geprüft: Ein fehlender Marker, dessen supersedes/supersededBy Links übereinstimmen, erscheint als worktree_reset_interrupted, niemals als worktree_marker_missing. Siehe unten den Abschnitt zur Route für das Übertragungsprotokoll und die Fehler-Taxonomie.

Die Workspace-Funktions-Tags und workspaces[] sind dynamisch. Clients, die einen Workspace hinzufügen, müssen /capabilities erneut abrufen, nachdem die Mutation abgeschlossen ist; der Daemon sendet keine Fähigkeitsänderungen an Clients, die eine frühere Antwort gecacht haben. Das Vergessen der Persistenz entlädt keine aktive Laufzeitumgebung, sodass diese Laufzeitumgebung bis zum Neustart weiterhin angezeigt wird.

GET /brand

Das Produkt-Branding der Web Shell für Hosts, die die Shell white-labeling möchten. Aufgelöst aus ui.brand in den Operator-Einstellungsbereichen. Gated durch das web_shell_brand Funktions-Tag; ein Daemon ohne die Route antwortet mit 404.

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

Beide Felder sind optional, und {} ist eine normale Antwort. Ein fehlendes Feld bedeutet “verwenden Sie die eingebaute Marke des Clients” — die Web Shell rendert ihren eigenen Namen und ihr eigenes Inline-Logo. Clients dürfen einen leeren Body nicht als Fehler behandeln.

Der Handler antwortet immer mit 200, auch wenn das konfigurierte Logo abgelehnt wurde. Eine fehlende Datei, ein Symlink, eine hardverlinkte Datei, ein Verzeichnis, ein Nicht-SVG-Dokument oder Inhalte über 32 KiB führen zu einem Body ohne logoDataUri, und der Grund wird in den stderr des Daemons als qwen serve: GET /brand: ui.brand.logoPath … geschrieben. Ein Client kann daher nicht zwischen “kein Brand konfiguriert” und “das Logo des Operators wurde abgelehnt” unterscheiden; der Kanal für den Operator ist das Daemon-Log. Eine Warnung ist weniger streng als eine Ablehnung, und es gibt zwei davon: ein Root-<svg> ohne nutzbaren viewBox und ohne positive, nicht-prozentuale width/height (ein fehlerhaftes oder nullflächiges viewBox zählt als unbrauchbar), das der Browser bei fester Seitenleistenbreite möglicherweise leer rendert; und ein Präfix-gebundener Root, dessen unprefixed Elemente keine Default-Namespace-Bindung haben, was sie unsichtbar macht. Middleware vor dem Handler antwortet, bevor er überhaupt ausgeführt wird — 401, wenn Bearer-Auth erforderlich aber nicht vorhanden ist, 429, wenn der optionale Rate Limiter aktiviert ist. Ein drainender Daemon lehnt diese Route nicht ab: Der Rate Limiter ist während des Drains permissiv, sodass der Handler weiterhin 200 antwortet, bis der Listener schließt und der Client einen Verbindungsfehler sieht. Der Start ist auf dieser Route kein 503: Auf dem Standard-Pfad für verzögerte Laufzeitumgebung wird die Anfrage gehalten, bis die Laufzeitumgebung bereit ist, und dann mit 200 beantwortet, sodass ein kurzer Client-Timeout frühzeitig feuern kann. Ein 503 mit code: "daemon_runtime_starting" erreicht diese Route nur bei Konfigurationen, die antworten, bevor die Laufzeitumgebung bereit ist (z. B. --open) und ist wiederholbar; ein 503 mit code: "daemon_runtime_failed" ist endgültig, bis der Daemon neu startet, und enthält kein Retry-After — versuchen Sie es nicht erneut.

Workspace-Einstellungen tragen niemals dazu bei. Die Route lädt Einstellungen mit skipWorkspaceSettings, sodass die .qwen/settings.json eines Repositorys weder den Produktnamen ändern noch eine Datei benennen kann, die der Daemon liest und in jeden verbundenen Browser inline einfügt. Nur System Defaults, User und System werden gelesen, in dieser Reihenfolge der Vorrangigkeit. Aus demselben Grund wird ein Brand-Wert mit einer Warnung im stderr des Daemons abgelehnt, wann immer die Platzhalterersetzung ihn ändern würde: Die Ersetzung bezieht sich auf die prozessweite Umgebung, die durch die .qwen/.env oder env-Blöcke eines Workspace beim Booten zuerst gefüllt wird. Ein nicht auflösbarer Platzhalter (die Variable ist nicht gesetzt) wird wörtlich beibehalten, sodass ein Tippfehler in einer Variablen als literal Text erscheint, anstatt stillschweigend zurückzufallen.

logoDataUri muss als Bild gerendert werden, niemals als Markup injiziert. Der Daemon bereinigt das gelesene SVG nicht. SVG, das über ein img src oder einen favicon href geladen wird, kann Skript ausführen; SVG, das in das Dokument injiziert wird, kann das. Die Web Shell weist es nur einem Bildkontext zu, und diese Invariante macht die Abwesenheit eines Sanitizers sicher.

Prozess-global. Die Route nimmt keinen Workspace-Selektor und keine Session-ID entgegen: Der Wert leitet sich von der benutzerglobalen Konfiguration ab, ist also für jeden Workspace, den der Daemon bedient, gleich. Er wird nach bearerAuth und dem Rate Limiter registriert und vor dem Web Shell SPA-Fallback, sodass er JSON für jeden Accept Header beantwortet.

POST /workspaces

Registrieren Sie eine zusätzliche Workspace-Laufzeitumgebung. Der Pfad muss ein vorhandenes, zugängliches, absolutes Verzeichnis sein, das keinen anderen registrierten Workspace dupliziert oder verschachtelt. Die Registrierung ist prozesslokal, es sei denn, der Client sendet persist: true; Clients müssen persistent_workspace_registration vor der Anforderung der Persistenz prüfen. Wenn workspace_display_name beworben wird, kann die Anfrage auch ein optionales displayName enthalten.

Wenn git_workspace_clone beworben wird, akzeptiert dieselbe Route auch { "kind": "git", "url": "...", "target": "/absolute/new/path" }. Dieses Formular erfordert ein absolutes target, das noch nicht existiert, startet einen asynchronen Clone, registriert nichts und gibt 202 { "kind": "git-workspace-clone", "jobId": "..." } zurück. Die Antworten 201 und 200 unten beschreiben die synchronen cwd und scratch Formulare; das git-Formular registriert nichts, und der Fortschritt und Abbruch des Clones verwenden GET/DELETE /workspace-git-clone-jobs/:jobId.

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

Eine neu erstellte Laufzeitumgebung gibt 201 zurück; die Hochstufung eines bereits aktiven sekundären Workspaces auf persistent gibt 200 zurück. Erfolg bei Persistenz umfasst persisted: true:

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

displayName muss eine Zeichenkette sein, die nach dem Trimmen umliegender Leerzeichen nicht länger als 256 Zeichen ist. Ein leeres Ergebnis wird als kein Name behandelt, und interne C0 (U+0000–U+001F)- oder DEL (U+007F)-Steuerzeichen werden abgelehnt. JSON null ist kein Erstellungswert und gibt 400 invalid_display_name zurück; lassen Sie das Feld weg, um keinen initialen Namen anzugeben. Duplizierte Anzeigenamen sind erlaubt. Ein Name, der mit einer prozesslokalen Registrierung angegeben wird, gilt nur für diesen Daemon-Prozess; persist: true speichert ihn zusammen mit der persistenten Registrierung, damit er nach einem Neustart wiederhergestellt werden kann. Das Wiederholen der Anfrage für einen bereits persistenten Workspace ist idempotent und benennt ihn nicht um.

Fehler umfassen 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 und 501 persistence_not_available / not_implemented.

PATCH /workspaces/:workspace

Aktualisieren Sie eine aktive Workspace-Ressource, ausgewählt nach Workspace-ID oder URL-kodiertem absoluten cwd. Der Endpunkt unterstützt derzeit nur Metadaten für Anzeigenamen:

{ "displayName": "Payments Production" }

Senden Sie { "displayName": null }, um den Namen zu löschen. Hier ist null ein Löschsentinel nur für Aktualisierungen; Nicht-Null-Werte folgen denselben String-Normalisierungsregeln wie POST /workspaces. Die Antwort ist die aktualisierte { id, cwd, displayName?, primary, trusted, removable? } Workspace-Projektion. Laufzeitmetadaten werden immer aktualisiert. Wenn die Laufzeitumgebung passende persistente Registrierungsidentitäten hat, wird jeder Alias atomar über den bestehenden Schema-v1-Registrierungsspeicher aktualisiert; der Endpunkt erstellt oder fördert niemals eine persistente Registrierung.

Nicht unterstützte Felder schlagen fehl, anstatt stillschweigend ignoriert zu werden. Fehler umfassen 400 empty_patch / invalid_display_name / unsupported_field / workspace_mismatch, 409 workspace_registration_in_progress, 500 workspace_registration_store_error und 503 daemon_shutting_down.

DELETE /workspaces/:workspace

Entfernen Sie eine entfernbare sekundäre Laufzeitumgebung. Der Selektor folgt den Routing-Regeln für mehrere Workspaces und akzeptiert entweder eine Workspace-ID oder ein URL-kodiertes absolutes cwd. Der optionale JSON-Body ist { "force": boolean }; das Weglassen fordert eine Nicht-Force-Entfernung an.

Die Nicht-Force-Entfernung gibt 409 workspace_busy mit einer activity Momentaufnahme zurück, wenn die eingefrorene Laufzeitumgebung Sitzungen, Prompts, ausstehende Starts, ACP-Verbindungen, Speicheraufgaben oder Workspace-Kanal-Worker hat. Das Senden von { "force": true } fordert die Beendigung dieser Ressourcen an. Die Entfernung der Persistenz ist der Commit-Punkt: Die anschließende Bereinigung ist begrenzt und best-effort, Bereinigungsfehler werden protokolliert, und die logische Entfernung konvergiert dennoch, anstatt die Laufzeitumgebung wiederherzustellen. Eine erfolgreiche Antwort ist:

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

Eine sofort belegte Nicht-Force-Anfrage gibt eine schnelle Pre-Drain-Aktivitätsmomentaufnahme zurück. Sobald der Drain beginnt, enthält die Antwort bei Belegung oder Erfolg die finale Momentaufnahme, die nach dem Schließen der Zulassungs- und ACP-Drain-Gates und vor Beginn der Bereinigung aufgenommen wurde. Fehler umfassen 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 und 503 daemon_shutting_down.

GET /workspace-registrations

Listen Sie den persistierten gewünschten Workspace-Satz für diesen primären Workspace auf. Einträge bleiben sichtbar mit active: false, wenn ein gespeicherter Verzeichnis während des aktuellen Starts nicht wiederhergestellt werden konnte. Ein Eintrag bleibt active: true, solange seine Laufzeit entleert wird, da die Laufzeit weiterhin Live-Ressourcen besitzt, bis die Entfernung abgeschlossen ist. Einträge enthalten optionales displayName, wenn die persistente Registrierung eines hat.

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

Gibt 501 persistence_not_available zurück, wenn kein Registrierungsspeicher konfiguriert ist, und 500 workspace_registration_store_error, wenn der Speicher nicht gelesen werden kann.

DELETE /workspace-registrations/:id

Vergisst eine persistierte Registrierung. Dies entlädt keine aktive Laufzeit und beendet keine ihrer Sitzungen; restartRequired: true bedeutet, dass die aktive Laufzeit beim nächsten Daemon-Neustart verschwindet.

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

Gibt 404 workspace_registration_not_found, 500 workspace_registration_store_error oder 501 persistence_not_available zurück. Wie bei anderen Mutations-Routen erfordert dieser Endpunkt Mutations-Authentifizierung, wenn die Daemon-Authentifizierung aktiviert ist.

Nur-Lese-Laufzeitstatus-Routen

Diese Routen melden Daemon-seitige Laufzeit-Snapshots. Sie sind additive v1-Routen, ändern keinen Zustand und ändern nicht die Serve-Protokollversion. Workspace-Status-Routen starten nicht absichtlich den ACP-Kindprozess nur, weil ein Client eine GET-Route abfragt. GET /workspace/mcp gibt initialized: false mit einem leeren Snapshot zurück, wenn der Daemon im Leerlauf ist und keine aufbewahrte MCP-Beobachtung hält; wenn ein lebendes Kind früher geantwortet hat, spielt die Leerlauf-Lesung diese Beobachtung mit source: "cache" und ihrem ursprünglichen initialized-Wert nach. GET /workspace/skills liefert stattdessen eine aufbewahrte Daemon-Beobachtung oder Daemon-lokale Aufzählung und meldet initialized: false mit einem errors-Eintrag (wiederholbare Nichtverfügbarkeit, kein leerer Katalog), nur wenn keine aufbewahrte Beobachtung existiert und beide Quellen nicht verfügbar sind (oder eine kalte Lesung gedrosselt wird) – siehe GET /workspace/skills. GET /workspace/providers wird Daemon-lokal aus Workspace-Einstellungen und Umgebung beantwortet, hängt also nicht von einem lebenden ACP-Kind ab, und acpChannelLive meldet die Lebendigkeit. Sein initialized ist true auf dem Erfolgspfad und false mit einem errors-Eintrag, wenn Workspace-Einstellungen oder Modellkonfiguration nicht aufgelöst werden können; Daemons, die ohne einen Daemon-lokalen Provider-Builder konstruiert wurden, fallen auf den lebenden ACP-Snapshot zurück, und die Daemon-lokale Antwort lässt runtime-registrierte Modelle weg. Session-Status-Routen erfordern eine lebende Session und geben 404 { code: "session_not_found", ... } für unbekannte IDs zurück.

Fähigkeits-Tags:

• workspace_mcp → GET /workspace/mcp
• workspace_skills → GET /workspace/skills
• workspace_providers → GET /workspace/providers
• workspace_acp_status → GET /workspace/acp/status
• workspace_env → GET /workspace/env
• workspace_preflight → GET /workspace/preflight
• session_context → GET /session/:id/context
• session_supported_commands → GET /session/:id/supported-commands
• session_tasks → GET /session/:id/tasks
• session_resources → GET /session/:id/resources
• session_monitor_tool_correlation → Monitor-Einträge aus GET /session/:id/tasks enthalten toolUseId zur Transkript-zu-Aufgabe-Korrelation
• session_status → GET /session/:id/status
• session_info → GET /workspace/:id/session-info und 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} und GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId

workspace_acp_status meldet die punktuelle Lebendigkeit des ACP-Kanals des primären Workspaces als { channelLive: boolean }. Der Handler erstellt keinen Kanal, aber das Erreichen einer Runtime-Route kann zuerst eine verzögerte Daemon-Laufzeit starten, deren konfigurierte Start-Richtlinie möglicherweise unabhängig ACP vorwärmt. Der Snapshot ist kein Lease: Clients müssen die Session-Erstellung zulassen, um den Kanal zu revalidieren oder zu starten.

ACP-Vorwärmen

Fähigkeits-Tag: workspace_acp_preheat.

POST /workspace/acp/preheat?timeoutMs=N initialisiert den ACP-Kanal des primären Workspaces best-effort. timeoutMs beträgt standardmäßig 5000 und muss eine positive Ganzzahl sein, die nicht größer als 60000 ist. Gleichzeitige Aufrufer und die Session-Erstellung teilen dieselbe Bridge-Initialisierung. Ein Anfrage-Timeout beendet nur diese HTTP-Wartezeit; er bricht die gemeinsame Initialisierung nicht ab.

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

ready ist immer gleich channelLive. Eine Live-Antwort lässt reason und error aus; andernfalls ist reason entweder timeout oder error. durationMs misst den aktuellen HTTP-Aufruf, nicht die gesamte Lebensdauer einer Initialisierung, an der der Aufruf teilgenommen hat. Ein operatives Timeout oder ein Fehler gibt HTTP 200 zurück. Ungültiges timeoutMs gibt 400 zurück, während Authentifizierungs-, Ratenbegrenzungs- und Fehler im verzögerten Runtime ihre normalen Antworten beibehalten.

Beide ACP-Arbeitsbereichsrouten sind singulär und nur für den primären Arbeitsbereich bestimmt. Clients dürfen sie nicht für einen sekundären Arbeitsbereich verwenden und weder Antwort als dauerhafte Bereitschaftszusage interpretieren.

Gemeinsame Statuszelle:

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 ist eine geschlossene Enumeration, die von /workspace/preflight, /workspace/env und (eventuell) MCP-Schutzmaßnahmen geteilt wird, damit SDK-Clients Maßnahmen pro Kategorie anzeigen können, anstatt frei formatierte Nachrichten zu parsen. Die ursprünglichen sieben Statusliterale stammten aus #4175; restore_timeout wurde separat für Sitzungs-Wiederherstellungsanfragen hinzugefügt. blocked_egress bleibt reserviert, bis die Egress-Probe implementiert ist.

Status-Nutzdaten geben niemals MCP-Umgebungswerte, Header, OAuth-/Service-Konto-Details, API-Schlüssel des Anbieters, Anbieter-baseUrl / envKey, Skill-Inhalt, Dateisystempfade des Skills, Hook-Definitionen oder Werte geheimer Umgebungsvariablen preis. /workspace/env meldet nur die Existenz von auf der Whitelist geführten Umgebungsvariablen; Proxy-URLs werden um Anmeldedaten bereinigt und vor der Übertragung auf host:port reduziert.

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 ist eines von not_started, in_progress oder completed. transport ist eines von stdio, sse, http, websocket, sdk oder unknown. errors wird weggelassen, wenn die Entdeckung erfolgreich ist.

source ist "live", solange das Kind, das die Beobachtung erzeugt hat, aktiv ist. Wenn der Daemon im Leerlauf ist und ein aktives Kind früher geantwortet hat, repliziert die Antwort diese Beobachtung mit source: "cache" und den ursprünglichen Werten des Kindes, einschließlich initialized: true und seiner Serverliste. Die zwischengespeicherte Beobachtung wird nur gelöscht, wenn eine neue MCP-Entdeckung beginnt; das Einziehen des Kindes verwirft sie nicht, sodass ein inaktiver GET /workspace/mcp einen Katalog melden kann, der derzeit von keinem aktiven Kind bereitgestellt wird.

MCP-Client-Schutzplanken (Issue #4175 ). Aktuelle Daemons erweitern die Nutzdaten um vier additive Felder und eine budgetbezogene Zelle mit Gültigkeitsbereich:

{
  "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 ist eines von enforce, warn oder off. clientBudget fehlt, wenn kein Budget festgelegt wurde. budgets[] ist immer ein Array bei Daemons, die mcp_guardrails anzeigen (möglicherweise leer, wenn budgetMode === 'off'); ältere Daemons lassen das Feld vollständig weg. Wenn mcp_workspace_pool angezeigt wird, hat die Zelle scope: 'workspace' und deckt den gemeinsamen Pool der ausgewählten Workspace-Laufzeitumgebung ab. Wenn dieses Tag fehlt, einschließlich unter QWEN_SERVE_NO_MCP_POOL=1, gibt der Legacy-Manager scope: 'session' aus. Verbraucher MÜSSEN zusätzliche unbekannte Scope-Werte tolerieren.

disabledReason auf serverbezogenen Zellen unterscheidet zwischen vom Betreiber deaktiviert ('config' — disabledMcpServers Konfigurationsliste) und durch Budget verweigert ('budget' — erkannt, aber aufgrund des enforce-Modus nie verbunden). Verweigerungen sind deterministisch nach der Deklarationsreihenfolge von Object.entries(mcpServers). Das serverbezogene status: 'error', errorKind: 'budget_exhausted' überlagert den rohen Wert mcpStatus: 'disconnected' (der wahr ist, aber nicht die für den Betreiber sichtbare Schweregradstufe darstellt).

Die Durchsetzung des Budgets ist fähigkeitsgesteuert. Mit mcp_workspace_pool teilen sich Sitzungen innerhalb einer Workspace-Laufzeitumgebung Transporte und ein WorkspaceMcpBudget; verschiedene Workspace-Laufzeitumgebungen teilen niemals einen Pool oder ein Budget. Ohne das Tag erzwingt jedes McpClientManager einer ACP-Sitzung seine eigene Kopie der Obergrenze, und der Snapshot stellt diese Legacy-Sitzungsansicht dar.

Erkennung von Budgetdruck. Zwei Oberflächen, beide nach PR-14b befüllt:

• Push-Ereignisse (angezeigt über mcp_guardrail_events): Abonnieren Sie GET /session/:id/events und filtern Sie mcp_budget_warning / mcp_child_refused_batch Frames über KnownDaemonEvent. Der Zustandsautomat feuert einmal pro Überschreiten der 75%-Schwelle nach oben (wird unterhalb von 37,5% neu scharf gestellt); Verweigerungen werden einmal pro Erkennungsdurchlauf im enforce-Modus zusammengefasst.

• Snapshot-Abfrage (angezeigt über mcp_guardrails): GET /workspace/mcp und überprüfen Sie die Budget-Zelle (budgets[0]) zusammen mit mcp_workspace_pool, um ihren Gültigkeitsbereich zu bestimmen:

• budgets[0].status === 'warning' ⇔ liveCount >= 0.75 * clientBudget (entspricht der Hysterese-Schwelle, die das Push-Ereignis von PR 14b verwenden wird).

• budgets[0].status === 'error' ⇔ refusedCount > 0 (ein oder mehrere Server wurden in diesem Erkennungsdurchlauf verweigert).

• budgets[0].status === 'ok' ⇔ unterhalb der 75%-Schwelle UND keine Verweigerungen.

Empfohlene Abfragefrequenz: abgestimmt auf alles, was bereits /workspace/mcp abfragt; der Snapshot ist günstig, und die Budget-Zelle verursacht keine zusätzlichen Erkennungskosten. SDK-Clients, die Push-Ereignisse abonnieren, profitieren dennoch vom Snapshot für den Zustand nach einer verlängerten Trennung (die Tiefe des SSE-Replay-Rings ist begrenzt — --event-ring-size, Standardwert 8000 — daher fällt ein Client, der länger als die Ringabdeckung offline ist, auf die Snapshot-Neusynchronisierung zurück).

GET /workspace/skills

Die primären und arbeitsbereichsqualifizierten Inventarrouten geben sofort eine beibehaltene Momentaufnahme zurück, während sie im Hintergrund revalidieren. Starts sind auf einmal pro Sekunde begrenzt, gemessen vom Task-Start, und parallele Leser teilen sich einen Task. Warme Hintergrund-Revalidierung gibt ihren Slot nach fünf Sekunden frei; ein Timeout erlaubt einen erneuten Versuch, bricht aber weder die Beobachtung noch die ACP-Arbeit ab. Kalte Lesevorgänge respektieren den konfigurierten Anfrage-Timeout von ACP (standardmäßig zehn Sekunden), danach folgt die daemon-lokale Aufzählung, falls ACP nicht verfügbar ist. Sie erzwingen weder die Hintergrund-Frist für eine Quelle. Ein kalter Lesevorgang, der innerhalb einer Sekunde nach seinem Start fehlschlägt, führt dazu, dass der Rest dieses Fensters sofort einen nicht verfügbaren Status zurückgibt; langsamere Fehler hinterlassen kein Drosselfenster, sodass Clients ihr eigenes Retry-Backoff benötigen. Eine späte erfolgreiche Hintergrundbeobachtung kann veröffentlichen, während ein erneuter Versuch aussteht, kann aber keine Beobachtung ersetzen, die später gestartet wurde und bereits veröffentlicht hat. Invalidierte Tasks können nicht veröffentlichen; eine erfolgreiche invalidierte Beobachtung kann weiterhin ihren ursprünglichen Aufrufer beantworten. Explizite Invalidierung verwirft bekanntermaßen ungültiges Inventar und löscht die Drosselung. Ein erfolgreicher ACP-Vorheizvorgang, der vor seinem Timeout abgeschlossen wird, invalidiert auch das beibehaltene Inventar, einschließlich wenn das Kind bereits aktiv war, sodass der folgende Lesevorgang das Kind sieht. Ein Vorheizvorgang, der ein Timeout erreicht und dann den Kanal aktiv findet, meldet ebenfalls ready: true — bereit ist immer gleich channelLive — behält aber das beibehaltene Inventar bei, da der Start möglicherweise noch unvollständig ist; der nächste Lesevorgang gibt diese beibehaltenen Daten zurück, und die Hintergrund-Revalidierung ersetzt sie, sobald die eine-Sekunden-Start-Drosselung es erlaubt. Das Löschen eines Skills umgeht die Momentaufnahme und die Drosselung, erfordert jedoch einen frisch aufgezählten Katalog: Es verwendet den lokalen Fallback und antwortet niemals aus einer beibehaltenen Momentaufnahme. Identitäts-Lesevorgänge zur Aktivierung umgehen die Momentaufnahme und die Drosselung, warten auf eine neue Beobachtung mit lokalem Fallback und dann auf die beibehaltene Momentaufnahme, wenn beide Quellen fehlschlagen.

Inventarantworten, die eine beibehaltene Daemon-Beobachtung enthalten, umfassen zusätzlich optionale Metadaten der Momentaufnahme. Direkte Konfigurations-/Runtime-Status-Lesevorgänge, Ressourceninventare der Sitzung und ältere Daemons lassen sie weg. Ein überholter erfolgreicher kalter Lesevorgang gibt eine neuere beibehaltene Momentaufnahme zurück, wenn verfügbar; andernfalls gibt er seine eigene ungecachte Beobachtung ohne diese Metadaten zurück. Nur initialisierte Beobachtungen ohne Fehler können die beibehaltene Momentaufnahme ersetzen:

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

observedAt ist die Unix-Millisekunden-Startzeit der erfolgreichen Beobachtung; ageMs wird pro Antwort neu berechnet und schließt konservativ die Sammelzeit ein. stale bedeutet, dass die Beobachtung mindestens eine Sekunde alt ist. refreshing gibt an, ob eine Revalidierung den gemeinsamen Slot belegt; abgelaufene Beobachtungen können noch nach Freigabe des Slots abgeschlossen werden. Fehlgeschlagene Lesevorgänge, Slot-Timeouts und Wiederholungen nach dem Stoppen der Laufzeit erneuern den Zeitstempel nicht; eine spätere erfolgreiche Veröffentlichung verzeichnet ihre eigene Beobachtungsstartzeit. Clients dürfen dieses Alter anzeigen, aber es handelt sich weder um eine Dateisystemrevision noch um einen Nachweis, dass jede Sitzung aktuell ist. Wenn kein initialisierter Snapshot existiert und beide Quellen nicht verfügbar sind (oder der Kaltstart-Lesevorgang gedrosselt wird), enthält die Antwort initialized: false, einen Eintrag errors und keine Metadaten snapshot. Dies ist ein wiederholbarer Nichtverfügbarkeitszustand, kein leerer Katalog; ein gültiger leerer Katalog hat initialized: true. Statusabfragen rufen keine sitzungsbetreffenden Skill-Aktualisierungsbefehle auf. Geschlossene oder entleerende Workspace-Laufzeiten lehnen Lesevorgänge ab; gespeicherte Daten überleben das Bereinigen von Kind-Kanälen, nicht die Stilllegung der Laufzeit.

{
  "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 ist einer von project, user, extension oder bundled. userInvocable (boolean, optional) wird für normale Skills weggelassen (was true bedeutet) und ist nur als false vorhanden, wenn der Skill nicht manuell aufgerufen werden kann. Es steuert nicht die unten beschriebenen reinen Einstellungs-Skill-Toggle-Routen. modelInvocable ist unabhängig: false bedeutet, dass der Skill weiterhin manuell verfügbar bleibt, aber vor Modellaufrufen verborgen ist. installedPath ist der bestehende absolute Pfad zum SKILL.md des Skills; der Daemon gibt ihn wie gespeichert zurück, ohne Symlinks separat aufzulösen oder zu kanonisieren. Aktuelle Daemons geben ihn für jeden Skill aus, während Clients seine Abwesenheit bei älteren v1-Daemons tolerieren müssen. Skill-Inhalte, Hooks, skillRoot und andere Skill-Konfigurationen bleiben ausgeschlossen. errors wird weggelassen, wenn die Erkennung erfolgreich ist.

Für Skills im Besitz einer Erweiterung ist extensionName der kanonische Manifestname und kann sicher als Besitzeridentität verwendet werden. extensionDisplayName ist ein optionaler, lokalisierter Anzeigewert und kann nicht eindeutig sein. Neue Clients sollten extensionDisplayName ?? extensionName anzeigen; ältere Daemons lassen das Anzeigefeld weg.

Wiederholte Lesevorgänge werden aus dem zuletzt committeten Workspace-Snapshot bedient und periodisch gegen den In-Memory-Cache des Kind-Prozesses revalidiert. Lesevorgänge im stabilen Zustand durchsuchen keine Skill-Verzeichnisse und parsen keine SKILL.md-Dateien erneut; der lokale Kaltstart-Fallback des Daemons kann vom Datenträger enumerieren. Das Kind überprüft, dass seine Erweiterungsquellen unverändert sind — ein readdir des Erweiterungsverzeichnisses plus ein stat pro Eintrag, die Aktivierungsdatei und der Aktivierungszustand des Speichers — und aktualisiert nur, wenn sie sich geändert haben, sodass eine außerhalb des Daemons installierte oder umgeschaltete Erweiterung durch die Revalidierung erfasst wird und bei einem nachfolgenden Lesevorgang erscheint, nachdem diese Revalidierung veröffentlicht wurde. Ein warmer Lesevorgang gibt immer die gespeicherte Beobachtung zurück, auch wenn er Hintergrundarbeit startet. Der sichere Modus und der reine Modus überspringen die Überprüfung, was ihrem Ausschluss von Erweiterungen entspricht.

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

Modelle sind nach Authentifizierungstyp gruppiert. Diagnostics zur Provider-Verbindung befinden sich in der Zelle providers von /workspace/preflight; die Umgebungsvorprüfung befindet sich in /workspace/preflight und /workspace/env (unten). errors wird weggelassen, wenn die Snapshot-Erstellung erfolgreich ist.

GET /workspace/env

Berichtet die Laufzeitumgebung, Plattform, Sandbox, Proxy und die Existenz von auf der Whitelist stehenden geheimen Umgebungsvariablen des Daemon-Prozesses. Beantwortet immer aus dem process.*-Zustand — der Daemon startet niemals einen ACP-Kind-Prozess, um diese Route zu bedienen, und die Antwort ist identisch, ob ACP aktiv oder im Leerlauf ist. Das Feld acpChannelLive ist nur informativ.

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

Zellform:

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

Redaktionsrichtlinie. Zellen kind: 'env_var' enthalten niemals ein Feld value; Clients sehen nur present: boolean. Zellen kind: 'proxy' leiten den rohen Umgebungsvariablenwert durch die Credential-Redaktion (redactProxyCredentials) und dann durch die Analyse von URL, sodass die Leitung nur host:port überträgt. NO_PROXY wird wortwörtlich durch die Redaktion geleitet, da es sich um eine Hostliste handelt und nicht um eine URL. Die Whitelist der enumerierten geheimen Umgebungsvariablen umfasst derzeit OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, DASHSCOPE_API_KEY, OPENROUTER_API_KEY und QWEN_SERVER_TOKEN. Andere Umgebungsvariablen werden nicht enumeriert, sodass versehentlich gesetzte Geheimnisse unsichtbar bleiben.

GET /workspace/preflight

Berichtet Bereitschaftsprüfungen des Daemons. Daemon-Ebene-Zellen (node_version, cli_entry, workspace_dir, ripgrep, git, npm) werden immer aus process.* und node:fs gefüllt. ACP-Ebene-Zellen (auth, mcp_discovery, skills, providers, tool_registry, egress) erfordern einen aktiven ACP-Kind-Prozess — wenn der Daemon im Leerlauf ist, geben sie Platzhalter status: 'not_started' aus. Die Route startet niemals ACP allein, um Zellen zu füllen; die entsprechenden Zellen fallen auf not_started zurück.

Leerlaufantwort (kein ACP-Kind):

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

Zellform:

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

errorKind-Semantik:

• missing_binary — Node-Version unterhalb der erforderlichen Version, fehlendes QWEN_CLI_ENTRY, ripgrep / git / npm nicht im PATH (Warnungen statt Fehler für optionale Binärdateien).
• missing_file — boundWorkspace existiert nicht oder ist kein Verzeichnis; Skill-Parse-Fehler, der auf eine fehlende oder unlesbare Datei hinweist.
• parse_error — SKILL.md Parse-Fehler, fehlerhaftes Konfigurations-JSON.
• auth_env_error — validateAuthMethod gab eine nicht-null Fehlerzeichenkette zurück, oder eine Unterklasse von ModelConfigError wurde aus der Provider-Auflösung propagiert.
• init_timeout — withTimeout Ablehnung in der Brücke (ein tatsächlicher Timeout beim Warten auf einen ACP-Roundtrip). Erkannt über die typisierte Klasse BridgeTimeoutError. Hinweis: Eine transiente Zelle mcp_discovery warning mit connecting > 0 trägt NICHT diese Art — das ist ein normaler Handshake-in-progress-Zustand, unterschiedlich von einem echten Timeout.
• restore_timeout — Das Laden oder Fortsetzen einer Sitzung hat das dedizierte Wiederherstellungsbudget überschritten. Die REST-Antwort ist 504 und kann wiederholt werden; sie unterscheidet sich von der Initialisierung des untergeordneten Prozesses und von den begrenzten Grenzen für das Replay-Fenster.
• protocol_error — ACP extMethod wurde abgelehnt, da der Kanal mitten in der Anfrage geschlossen wurde oder die Tool-Registry unerwartet fehlte.
• blocked_egress — Reserviert für PR 14 (#4175). PR 13 lässt die Zelle egress als status: 'not_started'.

Wenn die Brücke während der Bearbeitung einer Preflight-Anfrage (z. B. Schließung des Kanals mitten in der Anfrage) den ACP-Kind-Prozess nicht erreichen kann, enthält das Array errors im Umschlag eine einzelne Beschreibung ServeStatusCell des Fehlers, und die Zellen fallen auf ACP-Platzhalter not_started zurück. Daemon-Ebene-Zellen werden weiterhin zurückgegeben.

GET /workspace/tools

Gibt den vom ACP-Kind-Prozess des primären Arbeitsbereichs gemeldeten Tool-Katalog zurück. Dies ist eine Legacy-Route für den primären Arbeitsbereich: Sie verfügt über keinen Arbeitsbereichs-Selektor und darf nicht verwendet werden, um Tools einer Nicht-Primär-Laufzeitumgebung abzuleiten.

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

Wenn kein ACP-Kind-Prozess aktiv ist, gibt die Route weiterhin 200 mit acpChannelLive: false, einem leeren Array tools und einem Eintrag not_started im optionalen Array errors zurück. Unerwartete Brückenfehler verwenden die Standard-Brückenfehlerantwort 500. Die TypeScript-SDK-Methode ist workspaceTools(); es gibt kein dediziertes Capability-Tag, daher sollten Clients, die ältere Daemons unterstützen, 404 als nicht unterstützt behandeln.

Arbeitsbereich-Datei-Routen

Legacy-Dateirouten lösen Pfade über den primären Arbeitsbereich auf; Routen /workspaces/:workspace/... lösen Pfade über den Arbeitsbereich der ausgewählten Laufzeitumgebung auf. Antworten verwenden arbeitsbereichsrelative Pfade und geben bei normalem Erfolg niemals absolute Dateisystempfade zurück. Erfolgreiche Dateiantworten enthalten:

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

Dateisystemfehler verwenden dieses JSON-Format:

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

Die Werte von errorKind umfassen 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 und ambiguous_text_match.

GET /file

Liest eine Textdatei. Abfrageparameter: path (erforderlich), maxBytes, line, limit und cursor. Der Daemon lehnt Binärdateien ab. Dateien, die die Obergrenze für Vollständige-Snapshots von 256 KiB überschreiten, erfordern mindestens ein explizites Fensterargument (line, limit oder maxBytes); eine Anfrage ohne eines dieser Argumente bleibt file_too_large. Ein solches Fenster wird gestreamt, und sein zurückgegebener UTF-8-Inhalt bleibt auf 256 KiB begrenzt. maxBytes gilt immer für die UTF-8-Antwortbytes nach dem Decodieren, auch wenn die Quelle eine andere unterstützte Kodierung innerhalb der Obergrenze für Vollständige-Snapshots verwendet.

Zeilenverschiebungen werden durch Scannen vom Anfang der Datei aufgelöst, daher wird ein Fenster auch mit file_too_large abgelehnt, wenn das Erreichen mehr als 8 MiB lesen würde (MAX_TEXT_SCAN_BYTES). Verwenden Sie GET /file/bytes, um eine tiefere Verschiebung direkt zu erreichen. Großer Text in einer Kodierung, die die Route nicht decodieren kann, gibt binary_file zurück, nicht file_too_large — ein erneuter Versuch mit einem kleineren Fenster hilft nicht, und readBytes ist dasselbe Mittel, das bereits für Binärdateien gilt.

Für Dateien innerhalb der Obergrenze für Vollständige-Snapshots enthält die Antwort hash, einen SHA-256-Digest über die Rohbytes auf der Festplatte für die gesamte Datei, auch wenn line, limit oder maxBytes einen Ausschnitt zurückgegeben haben. Große partielle Fenster lassen hash weg, behalten den vollständigen sizeBytes bei, setzen truncated: true und geben originalLineCount: null zurück, wenn der Stream vor EOF stoppt.

Paging mit cursor

Erfordert die Capability workspace_file_read_cursor. Eine Antwort, die noch mehr Inhalt hat, gibt hasMore: true zurück und, wenn ein Datei-Byte-Offset ableitbar ist, ein Token nextCursor. Wenn dieses als cursor zurückgegeben wird, wird in O(1) fortgesetzt, wobei eine tiefe Verschiebung line ein Scannen von Byte 0 erfordert und über 8 MiB hinaus abgelehnt wird.

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

cursor und line sind gegenseitig ausschließend (parse_error) — beide benennen einen Startpunkt. Ein fehlerhafter oder zu langer Cursor führt zu parse_error; ein Cursor, dessen Datei ersetzt oder gekürzt wurde, führt zu hash_mismatch (409). Anhängen macht keinen ausstehenden Cursor ungültig, was der Fall ist, für den diese Funktion existiert.

content lässt den abschließenden Zeilenumbruch seiner letzten Zeile weg, wie jede andere Leseoperation, sodass ein Client, der Seiten zusammensetzt, sie mit \n verbindet. hasMore ist keine Neuformulierung von nextCursor: Eine kleine Nicht-UTF-8-Datei, die mit einem limit gelesen wird, hat mehr Inhalt, aber keinen ableitbaren Byte-Offset, daher meldet sie hasMore: true mit nextCursor: null. Der Cursor ist auch null, wenn die Byte-Obergrenze die aktuelle Zeile schneidet, da das Fortsetzen von diesem Offset eine teilweise Zeile zurückgeben würde. Für viele kurze Zeilen senken Sie limit, bis die Seite endet, bevor die Byte-Obergrenze erreicht wird und einen Cursor zurückgibt. Für eine einzelne übergroße Zeile fordern Sie die folgende Zeile explizit an (zum Beispiel line=2 beim Start bei Zeile 1), fahren dann mit Cursoren fort; verwenden Sie GET /file/bytes, wenn die vollständige übergroße Zeile erforderlich ist.

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

Liest Rohbytes aus einer Datei ohne Decodierung. Abfrageparameter: path (erforderlich), offset (Standardwert 0) und maxBytes (Standardwert 65536, Maximum 262144). Diese Route unterstützt begrenzte Fenster auf großen Binärdateien, ohne die gesamte Datei einzulesen. Die Antwort enthält hash nur, wenn das zurückgegebene Fenster die gesamte Datei abdeckt.

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

GET /stat

Gibt Metadaten für einen Pfad im primären Arbeitsbereich zurück. Der Abfrageparameter path ist erforderlich.

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

type ist file, directory, symlink oder other. Die Route verwendet die Arbeitsbereichs-Dateigrenze und den oben beschriebenen gemeinsamen Dateisystem-Fehlerumschlag. Die TypeScript-SDK-Methode ist fileStat().

GET /list

Listet ein Verzeichnis des primären Arbeitsbereichs auf. Der Abfrageparameter path ist erforderlich; includeIgnored=1 (oder true) schließt Einträge ein, die mit Ignorierregeln übereinstimmen. Die Antwort ist auf 2.000 Einträge begrenzt und setzt truncated: true, wenn weitere existieren.

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

Das kind jedes Eintrags ist file, directory, symlink oder other. Die TypeScript-SDK-Methode ist dirList().

GET /glob

Sucht nach Pfaden im primären Arbeitsbereich. Der Abfrageparameter pattern ist erforderlich. Optional verfeinert cwd die Suche, includeIgnored=1 (oder true) schließt ignorierte Pfade ein, und maxResults ist eine Ganzzahl von 1 bis 50.000 (Standardwert 5.000).

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

Übereinstimmungen sind relativ zum Arbeitsbereich. Ungültige Abfragewerte geben 400 zurück; Vertrauenswürdigkeit des Arbeitsbereichs, Enthaltensein, fehlender Pfad und unerwartete Fehler verwenden den gemeinsamen Dateisystem-Fehlerumschlag. Die TypeScript-SDK-Methode ist glob().

POST /file/write

Erstellt oder ersetzt eine Textdatei. Dies ist eine strikte Mutationsroute: Eine vertrauenswürdige Loopback-Anfrage ohne Token für den primären Bereich wird autorisiert. Eine primäre Anfrage ohne Token, die das Gate ohne vertrauenswürdige Loopback-Autorisierung erreicht, gibt 401 { "code": "token_required" } zurück. Konfigurierte Token- und Local Control-Credential-Fehler werden früher mit einfachem 401 Unauthorized abgelehnt; mit --require-auth lehnt das globale Bearer-Middleware nicht authentifizierte Anfragen ab, bevor die Route ausgeführt wird.

Body:

{
  "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 muss create oder replace sein. create überschreibt niemals eine vorhandene Datei (409 file_already_exists). replace erfordert expectedHash; fehlende oder fehlerhafte Hashes sind 400 parse_error, und veraltete Hashes sind 409 hash_mismatch. expectedHash ist sha256: plus 64 kleine Hexadezimalzeichen, berechnet über die rohen Bytes auf der Festplatte.

bom, encoding und lineEnding können angegeben werden. Ersetzungen bewahren standardmäßig das Kodierungsprofil der vorhandenen Datei bei; explizite Felder setzen dies außer Kraft. Binäre Schreibvorgänge sind nicht Teil des Anwendungsbereichs.

Der Daemon schreibt in eine zufällige temporäre Datei im Zielverzeichnis, ruft fsync auf, wo unterstützt, prüft den aktuellen Hash unmittelbar vor rename() erneut und benennt sie dann an Ort und Stelle um. Dies verhindert die Beobachtung unvollständiger Dateien und serialisiert Daemon-originierte Schreibvorgänge auf dieselbe Datei, ist aber kein prozessübergreifender Kernel-Vergleich-und-Austausch: Ein externer Editor kann immer noch im kleinen Zeitfenster zwischen letzter Hash-Prüfung und Umbenennung eingreifen.

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

Wendet eine exakte Textersetzung auf eine vorhandene Textdatei an. Dies ist ebenfalls eine strikte Mutationsroute und erfordert expectedHash.

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

oldText darf nicht leer sein und muss genau einmal vorkommen. Keine Übereinstimmung gibt 422 text_not_found zurück; mehrere Übereinstimmungen geben 422 ambiguous_text_match zurück. Die Route bewahrt Kodierung, BOM und Zeilenenden bei und prüft expectedHash unmittelbar vor der atomaren Umbenennung erneut.

Explizite Schreib-/Bearbeitungsvorgänge auf ignorierten Pfaden sind erlaubt, da der authentifizierte Aufrufer den Pfad benannt hat. Erfolgsantworten und Audit-Ereignisse enthalten 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

Erfordert workspace_qualified_rest_core und workspace_directory_create, strikte Mutationsautorität und einen vertrauenswürdigen aktiven lokalen Arbeitsbereich. Body:

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

Das Elternverzeichnis muss existieren. Die Erstellung ist exklusiv: Eine vorhandene Datei oder ein vorhandenes Verzeichnis gibt 409 file_already_exists zurück; ein abschließender Symlink gibt 400 symlink_escape zurück. Erfolg ist 201 { "kind": "directory_create", "path": "src/new-folder" }. Die SDK-Methode ist WorkspaceDaemonClient.createWorkspaceDirectory(path, clientId?).

POST /workspaces/:workspace/directory/delete

Erfordert workspace_qualified_rest_core und workspace_directory_delete unter derselben Richtlinie für strikte Mutation und vertrauenswürdige lokale Laufzeitumgebung. Body:

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

Löscht ein leeres oder nicht leeres Verzeichnis rekursiv. Arbeitsbereichswurzeln, reguläre Dateien und abschließende Symlinks werden abgelehnt; verschachtelte Symlink-Einträge werden entfernt, ohne ihren Zielen zu folgen. Ein fehlendes Ziel gibt 404 path_not_found zurück. Erfolg ist 200 { "kind": "directory_delete", "path": "src/old-folder" }. Die SDK-Methode ist WorkspaceDaemonClient.deleteWorkspaceDirectory(path, clientId?).

Beide Verzeichnisrouten bewahren den lexikalischen finalen Namen, während sie dessen Eltern innerhalb des ausgewählten Arbeitsbereichs auflösen. Pfade dürfen nicht auf einem Trennzeichen enden; verdächtige Pfadmuster geben 400 path_outside_workspace zurück, während fehlerhafte Blattformen 400 parse_error zurückgeben. Nicht unterstützte benutzerdefinierte Fabriken geben 422 zurück; SSH-Arbeitsbereiche werden durch die SSH-Grenze mit 501 abgelehnt. Unbekannte, nicht verfügbare, entfernte oder nicht vertrauenswürdige Besitzer fallen niemals auf den primären Bereich zurück.

Löschungen sind permanent und Fehler können teilweise Entfernung hinterlassen. Ein gleichzeitiger Schreiber kann ENOTEMPTY verursachen, zurückgegeben als 503 io_error; wiederholen Sie denselben Vorgang, nachdem der Schreiber gestoppt hat. Sperren pro Pfad serialisieren ein Verzeichnis nicht gegen jeden Kind-Schreibvorgang, und ein externer Verzeichnisaustausch kann durch portable pfadbasierte Prüfungen nicht atomar gemacht werden. Explizite Mutationen ignorierter Verzeichnisse sind erlaubt, und Audit-Ereignisse annotieren matchedIgnore, wenn zutreffend; Erstellungsaufzeichnungen sizeBytes: 0.

GET /session/:id/context

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

Für eine Top-Level-Sitzung spiegelt state dieselben ACP-Modell-/Modus-/Konfigurationsoptionsformen wider, die von POST /session, POST /session/:id/load und POST /session/:id/resume verwendet werden. Eine virtuelle Sitzungs-ID mit Präfix subagent. löst sich gegen ihre Eltern-Laufzeit auf und gibt ein leeres state-Objekt zurück.

GET /session/:id/supported-commands

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

availableCommands ist derselbe Befehlsschnappschuss, der von der available_commands_update SSE-Benachrichtigung verwendet wird. availableSkills listet nur Skill-Namen auf; Clients dürfen keine Skill-Inhalte oder Pfade über diese Route erwarten.

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

Diese Route ist ein schreibgeschützter Out-of-Band-Schnappschuss. Sie ist absichtlich kein Prompt und kann abgefragt werden, während die Sitzung streamt. Die Antwort enthält nur whitelisted Metadaten aus den Agent-, Shell- und Monitor-Task-Registrierungen; Controller, Timer, Offsets, ausstehende Nachrichten und Roh-Registrierungsobjekte werden niemals offengelegt.

Agent-Tasks, die von einem anderen Sub-Agenten erzeugt wurden (verschachtelte Sub-Agenten, begrenzt durch maxSubagentDepth), enthalten drei optionale Lineage-Felder: parentAgentId (die id des erzeugenden Agent-Tasks), parentName (die subagentType des erzeugenden Agenten, erfasst bei der Registrierung, damit sie den Ausschluss des Elternprozesses aus dem Registry überlebt) und depth (0-basierte Starttiefe; 0 = vom Top-Level-Session erzeugt). Agenten, die von der Top-Level-Session gestartet werden, lassen parentAgentId und parentName weg; Clients sollten alle drei Felder als optional behandeln und auf eine flache Liste zurückgreifen, wenn sie fehlen.

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

Detailinformationen bei Bedarf für einen Shell-Task. GET /session/:id/tasks enthält nur Lifecycle-Fakten; diese Route liest die erfasste Ausgabedatei und prüft den Prozessbaum, sodass ein geöffnetes Detailfenster separat danach fragt.

Die ACP-Methode ist _qwen/session/task_runtime mit den Parametern sessionId und taskId. Beide Transports lösen den Besitzer der aktiven Session auf; ACP erfordert zusätzlich, dass die Verbindung die Session besitzt.

Das taskId des Pfads wird gegen das eigene Shell-Registry der Session aufgelöst; Aufrufer geben niemals einen Dateipfad an.

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

runtime ist null, wenn der Task unbekannt ist, ausgeschlossen wurde oder kein Shell-Task ist. memoryBytes ist der Resident Set des Prozessbaums der Shell, der nur während der Ausführung des Tasks abgetastet wird; geteilte Seiten werden einmal pro Prozess gezählt, und ein Container-Sandbox kann möglicherweise nur den Wrapper-Prozess offenlegen. outputTail ist auf dieselbe 8 KiB-Grenze beschränkt wie bei der Abschlussbenachrichtigung, und outputTailTruncated markiert ein Ende, das mitten in der Datei beginnt. outputError wird gesetzt, wenn die Datei nicht gelesen werden kann; Felder aus einem Teil, der erfolgreich war, können weiterhin vorhanden sein.

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

Steuert einen Workflow-Lauf oder startet einen neuen. Die ACP-Methode ist _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" }
}

Was taskId benennt, hängt von der Aktion ab:

args, sourceRef und script werden nur von run-saved und run-script gelesen. args ist an das globale args des Skripts gebunden und kann jeder JSON-Wert sein; sourceRef ist das eigene {id, revision} des Aufrufers, aufgezeichnet im Lauf, seinem Journal und seinem Snapshot; script ist die Quelle, die run-script ausführt, und wird davon benötigt. Ein Retry oder Rerun spielt das eigene args und sourceRef des ursprünglichen Laufs erneut ab – das macht es zum selben Lauf –, daher werden diese Felder zusammen mit den Steueraktionen ignoriert.

Ein gestarteter Lauf gehört zur Session: Er läuft im Hintergrund ohne Genehmigungsaufforderung, und seine Abschlussmeldung erreicht den Abschlusskanal der Session. Danach ist er ein retry/rerun-Ziel wie jeder andere Lauf.

retry und rerun akzeptieren auch einen aus dem Verlauf wiederhergestellten Lauf (isHistorical in GET /session/:id/tasks), wie z. B. einen, der durch einen Daemon-Neustart unterbrochen wurde: Der Lauf wird erneut aus dem Skript, args und sourceRef seines Snapshots gestartet, registriert sich bei der Session, die die Aktion gesendet hat, und meldet seinen Abschluss dorthin. Ein retry setzt das Journal des Laufs unter derselben Lauf-ID fort und gilt für einen failed-Lauf, bei dem kein Prozess mehr läuft; ein rerun startet eine neue Lauf-ID von einem beliebigen abgeschlossenen Lauf. Ein Verlaufeintrag mit argsOmitted wurde mit einem zu großen args gestartet, um ihn zu behalten, daher gilt keine der beiden Aktionen dafür. Auch nicht für einen Snapshot, der geschrieben wurde, bevor args behalten wurden, da dieser weder argsOmitted noch argsRecorded enthält: Das Journal eines Laufs ist über einen Hash seiner args indiziert, sodass das Neustarten eines Laufs, dessen args sein Verlauf nicht benennen kann, nichts wiedergeben würde und jeden Agenten neu dispatchen würde. Beide Ablehnungen sind workflow_args_unavailable, und GET /session/:id/tasks meldet beide als argsUnavailable am Eintrag, sodass ein Client die beiden Aktionen zurückhalten kann, statt die Ablehnung durch den Aufruf zu entdecken. argsOmitted bleibt daneben als Grund stehen, für einen Client, der angeben möchte, welcher. Die args selbst werden niemals über die Leitung geschickt.

run-script übergibt keinen Definitionsnamen, daher wird der Lauf durch das eigene export const meta des Skripts bezeichnet – ein kompiliertes Skript sollte einen deklarieren, sonst zeigt der Lauf nur seine ID.

Die Antwort ist {"changed": true, "status": "running", "taskId": "<runId>"} für einen gestarteten Lauf, {"changed": true, "status": "<status>"} für eine wirksame Steueraktion und {"changed": false}, wenn nichts passiert ist: Workflow ist für die Session nicht verfügbar (deaktiviert, Bare-Mode, nicht vertrauenswürdiger Ordner), der Workspace ist nicht vertrauenswürdig, der gespeicherte Workflow-Name ist unbekannt, die Lauf-ID ist unbekannt oder ein anderer Start ist bereits unter demselben taskId im Gange. Nur überlappende Starts werden dedupliziert: Zwei gleichzeitige run-script-Aufrufe unter einer taskId starten einen Lauf. Sobald dieser Start zurückkehrt, wird der Schlüssel freigegeben; erneutes Absenden kann einen weiteren Lauf starten, auch wenn der erste Lauf noch aktiv ist. Der Schlüssel bietet keine Retry-Idempotenz nach einem verlorenen Antwortpaket.

Ein abgelehnter Parameter ist ein 400 (-32602 über ACP), kein gestarteter Lauf: eine unbekannte action, eine run-script ohne script, eine sourceRef, die nicht {id, revision} aus nicht-leeren Strings ist, oder ein Skript, das vor dem Start wegen ungültiger Syntax oder Determinismusverletzung abgelehnt wurde. Eingabefehler beim Workflow-Start tragen workflow_invalid_params und behalten die Ablehnungsmeldung.

Vier Ablehnungen stammen aus dem gespeicherten Zustand des Laufs, nicht aus der Anfrage. Jede ist -32602 über ACP, trägt ihre errorKind und ihre data.httpStatus. Drei sind ein 409; die vierte, workflow_not_recorded, ist ein 503, weil nichts gestartet wurde und derselbe Aufruf einfach wiederholt werden kann: Ein retry vermerkt, dass der Lauf erneut läuft, bevor er startet – dieser Vermerk verhindert, dass ein anderer Prozess ihn ein zweites Mal startet – und der Vermerk konnte nicht geschrieben werden.

workflowToolFeatures in GET /session/:id/supported-commands bewirbt runSavedArgs und runScript; ein Daemon ohne diese akzeptiert weder die Starteingabe noch die run-script-Aktion. Er enthält auch nameOnly, wahr, wenn das Modell der Sitzung nur benannte Workflows ausführen darf (tools.workflowNameOnly): Die eigenen script- und scriptPath-Aufrufe des Modells werden abgelehnt, während jede oben genannte Aktion, einschließlich run-script, weiterhin Läufe startet. retryHistorical ist wahr, wenn retry und rerun einen aus dem Verlauf wiederhergestellten Lauf akzeptieren; ein älterer Daemon antwortet darauf mit {"changed": false}, daher sollte ein Client diese Steuerelemente für einen Verlaufsdatensatz nur anbieten, wenn dies gemeldet wird.

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