qwen serve HTTP プロトコルリファレンス

qwen-code デーモン設計  のステージ 1。すべてのルートは、デーモンのベース URL（デフォルト http://127.0.0.1:4170）の下にあります。

このリファレンスでは、HTTP ルートと SSE フレーミングについて説明します。ペイロード契約、再同期理由、履歴アンカーについては 型付きイベントスキーマ、配信とバックプレッシャについては イベントバスと再生ガイド、既存の v1 プロトコルと互換性ルールについては 機能とバージョン管理 を併せてお読みください。完全な契約セットへのリンクは デーモンドキュメントインデックス にあります。

認証

デーモンが --token または QWEN_SERVER_TOKEN で起動された場合 — または、いずれも指定されずに非ループバックにバインドされた場合（一時的なベアラートークンを生成し、起動時に一度だけ表示します）— 通常のループバックバインドでは /health を除くすべての通常 API ルートで次を運ぶ必要があります:

Authorization: Bearer <token>

ループバックデフォルトでトークンが設定されていない場合、ヘッダーはオプションであり、プライマリリスナー経由で到着するリクエストはフルオペレーター API 権限を持ちます。ワークスペース信頼性、セッション所有権、X-Qwen-Client-Id、権限、機能、検証、およびリソースチェックは依然として適用されます。トークン比較は定数時間です。401 レスポンスは missing header / wrong scheme / wrong token で一律です。

--open-with-auth。 このデフォルトオフの CLI モードには、ループバックバインドと利用可能な Web Shell が必要です。通常の --token-over-QWEN_SERVER_TOKEN 選択を再利用するか、その選択が空の場合、デーモン起動前に base64url エンコードされた 32 ランダムバイトを生成します。ブラウザは、#token= 経由で選択されたベアラートークンを受信し、タブごとに保存します。プロトコルとミドルウェアは、通常の設定済みトークンとして扱います。フラグメント配信キーは解決されたトークンに基づいており、このフラグには基づきません: すべての --open 起動は、解決されたベアラートークン（設定済みまたは生成済み）を起動 URL の #token= フラグメントに添付します（ローカルユーザーは ps / /proc を介して確認できます。ランチャーが警告するように）、したがって、裸の --open を伴う非ループバックバインドは、生成されたベアラートークンを同じようにブラウザに渡します。このフラグの独自の貢献は、ループバックでのトークン 生成 と、ブラウザ不適格環境での手動 URL フォールバックです。RunHandle.resolvedToken を無視する直接埋め込み呼び出し元のみ、およびブラウザを起動しないクライアントは、自動資格情報を受け取りません。ブラウザ不適格環境では、秘密を含むフラグメント URL が手動開き用に表示されます。ループバック /health と静的 Web Shell アセットは、以下で説明される免除を保持します。--require-auth は依然として /health をゲートします。

チャネル Webhook イングレス（POST /channels/:channelName/webhooks/:source）は、すべてのモードにおいてこのベアラート契約とは別個です。マウントされると、bearerAuth より前に登録され、設定済みの x-qwen-webhook-secret で認証します。デーモンベアラートトークンのローテーションは、Webhook ソースシークレットをローテーションしません。

/health 免除 (Bctum): ループバックバインド（127.0.0.0/8 / localhost / ::1 / [::1]）では、/health はベアラートミドルウェアより BEFORE に登録されるため、ポッド内のライブネスプローブは、デーモンが --token で起動された場合でもトークンを運ぶ必要がありません。非ループバックバインド（--hostname 0.0.0.0 など）は、他の通常 API ルートと同様に /health をゲートします — 根拠については GET /health セクションを参照してください。

--require-auth (#4175 PR 15)。 このフラグを起動時に渡すと、「トークンが必要」というルールがループバックにも拡張されます。トークンソースが解決されない場合、起動は失敗します — ループバックでは、--token、QWEN_SERVER_TOKEN、または --open-with-auth（これらは起動前に独自に生成されたトークンをインストールするため、--require-auth --open-with-auth が開始します）を意味します。fail-fast はループバック限定です: 非ループバックバインドは、設定済みソースのいずれも存在しない場合に生成される一時的なベアラートークンを解決し、これがフラグを満たします。/health 免除はいずれの場合も削除されるため、/health も Authorization: Bearer … が必要になります。

フラグがオンの場合、グローバル bearerAuth ミドルウェアは すべての通常 API ルート — /health と /capabilities を含む — をゲートします。チャネル Webhook イングレスは独立した共有シークレット認証のままとなり、Web Shell ドキュメントおよびアセットルートは事前認証のままとなります。したがって、未認証クライアントは、認証が必要であることを発見するために caps.features をプリフライトできません: そのケースの検出表面は 401 レスポンスボディ自体です（認証 セクションに従い、ベアラートゲートルート間で一律）。require_auth 機能タグは 認証後の確認 です — クライアントが正常に認証し /capabilities を読み取った後、タグの存在はデーモンが --require-auth で起動されたことを確認します（監査/コンプライアンス UI や、SDK クライアントが「このデプロイメントは強化されている」を設定パネルに表示するのに有用）。厳格な変更ルートは、信頼できるループバックプライマリリスナーリクエスト、ベアラート認証済みリクエスト、またはペアリングされた Local Control リクエストを受け入れます。信頼できないトークンなしの埋め込みは依然として 401 { code: "token_required", error: "…" } を受け取ります。--require-auth では、グローバルベアラートミドルウェアが最初にレガシーな Unauthorized ボディで拒否します。

--allow-origin <pattern> (T2.4 #4514 )。 デーモンにクロスオリジンでアクセスするブラウザクライアントはデフォルトでブロックされます — Origin ヘッダーを持つリクエストは 403 {"error":"Request denied by CORS policy"} を返します。これは、CLI/SDK クライアントが Origin を送信せず、デーモンはその存在を、オペレーターがオプトインしていないブラウザコンテキストから来たリクエストの兆候として扱うためです。トークンを持つ非ループバックバインドでは、壁の前に一つの例外があります: 同一オリジンリクエスト（Origin がダイレクトソケットスキームと正規化された Host オーソリティの合計と等しい）はベアラート認証され、その Origin は プライマリリスナー上で除去されます — 有効なベアラートがある場合はルート自身のステータスが従われ、ベアラートがないか無効な場合は 401 となりますが、事前認証の Web Shell ドキュメント、/assets/*、/manifest.webmanifest、/sw.js、および /mcp-app-sandbox ルートを除きます。これらは他のすべてのモードと同様に資格情報なしで提供されます — そして、クロスオリジンまたは一致しない Origin 値のみが 403 エンベロープを保持します。起動時に --allow-origin <pattern>（繰り返し可能）を渡すと、壁の代わりに許可リストをインストールします。各パターンは次のいずれかです:

• リテラルな * — あらゆる送信元を許可します。リスクあり: * が設定されているのにベアラートークンが解決されない場合、起動は拒否されます。ガードは 解決済み のトークン — --token、QWEN_SERVER_TOKEN、--open-with-auth で生成されるループバックトークン、または設定されたソースがない場合に非ループバインドで生成される一時的なベアラートークン — を読み取るため、この拒否はループバック限定です。起動時のブレットクラムは、* がリストに含まれている場合に stderr へ警告を出力します。推奨事項: ループバインドでは --require-auth と組み合わせて使用し、/health もベアラートークンで保護されるようにしてください。デフォルトではループバック上でベアラミドルウェアより前に登録されるため（k8s/Compose プローブがトークンなしで到達可能）、* の許可リストにより任意のクロスオリジンブラウザから到達可能になります。--require-auth でも Web Shell の静的アセット（/、/assets/*、/manifest.webmanifest、/sw.js、および /session/:id、/plugins、/channels、/live、/scheduled-tasks、/goals、および /settings ドキュメントナビゲーション）は設計上ループバック上で認証前アクセスが可能であり、ベアラミドルウェアより前にマウントされるため、* の許可リスト下では任意のクロスオリジンブラウザから読み取り可能です。--no-web はその表面を除去します。非ループバインドでは、ベアラートークンは起動時に必須であり、/health はその背後に配置されています。通常の API ルートはベアラートークンで保護され、チャネル Webhook インバースは独自の共有シークレットゲートを維持し、Web Shell の静的アセット（/、/assets/*、/manifest.webmanifest、/sw.js、および /session/:id、/plugins、/channels、/live、/scheduled-tasks、/goals、および /settings ドキュメントナビゲーション）は --no-web によって除去されない限り認証前アクセスのままです。
• 正規化された URL オリジン — <scheme>://<host>[:<port>]。末尾スラッシュなし、パスなし、ユーザー情報なし、クエリなし。 エントリが往復検証 new URL(pattern).origin === pattern に失敗した場合、起動は InvalidAllowOriginPatternError で拒否されます。エラーメッセージには不正なパターンと正規形式が記載されます。意図的な厳格性: 暗黙的な正規化（例: 末尾の / のトリミング）は誤字を見逃し曖昧な入力を許容してしまいます。解決済みのトークンがない場合 — 生成後はループバインドを意味します — HTTP(S) エントリはループバックホストに限定されます。非ループバックブラウザオリジンは、デーモンユーザーとしてのコード実行を含む完全なオペレーター API を駆動できる可能性があるため、トークンが必要です。明示的なブラウザ拡張機能のオリジンは、既存のトークン不要なローカル自動化パスを維持します。起動時、トークン不要で許可されたブラウザオリジンに付与される権限がログに記録されます。

マッチしたオリジンはすべてのリクエストに対して標準的な CORS レスポンスヘッダーを受け取ります:

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

Access-Control-Allow-Origin は、リクエストのオリジンをそのまま（ブラウザが送信した大文字小文字のまま）エコー返し、リテラルな * を返しません。* パターン下でも同様です。ブラウザキャッシュはこれと Vary: Origin をペアにしてレスポンスをキー付けするため、エコー返しによりスキーマ変更なしで将来のリリースで Access-Control-Allow-Credentials を追加する余地が残ります。公開ヘッダーにより、ブラウザクライアントは再試行ヒントに従い、SSE エポックを保持し、受け入れられた物理ストリームを相関させることができます。Access-Control-Allow-Credentials は現在 送信されません。設定されたデーモン資格情報は Authorization 内のベアラートークンを使用しており、credentials: 'include' なしでクロスオリジン動作が可能です。信頼できるループバック権限にはブラウザ資格情報が不要です。

OPTIONS プリフライトリクエスト（Access-Control-Request-Method または Access-Control-Request-Headers を伴う OPTIONS）は、204 No Content と上記ヘッダーで短絡応答します。これは慣例的な CORS パターンであり安全です。プリフライトはデーモンが受け入れるメソッド/ヘッダーを確認するのみで、実際の後続リクエストは Host ゲートを実行し、その後状態を読み書きする前にベアラートークン/リスナー権限またはチャネル Webhook 共有シークレットゲートを通ります。マッチしたオリジンからの通常の OPTIONS リクエストは、CORS ヘッダー付きで下流へ流れ続けます。

許可リストに一致しないオリジンも 403 {"error":"Request denied by CORS policy"} を取得します。デフォルトの壁と同じエンベロープのため、すでに壁のレスポンスを解析しているクライアントは許可リスト展開済みデーモンを特別扱いする必要がありません。拒否パスは Access-Control-* ヘッダーを発行しません（ブラウザは無視し、発行するとヘッダーの有無を通じて許可リストサイズを間接的に通知してしまうため）。

設定されたパターンリストは意図的に /capabilities にエコーされません。ブラウザクライアントは自身のオリジンを既に知っており（結局のところデーモンを呼び出したのは自分自身なので）、リストを開示すると未認証の /capabilities 読者がすべての信頼できるオリジンを列挙できてしまいます（誤設定された展開に対する有用な偵察情報となります）。SDK クライアントは「このデーモンはクロスオリジンブラウザヒットを尊重する」ことを判断するために caps.features.allow_origin タグでゲート制御を行い、具体的なオリジンを知らなくても済みます。

ループバック自己オリジンリクエスト（例: 同じ 127.0.0.1:port でデーモンを呼び出す Web Shell）は、CORS ミドルウェアより 前に 実行される別の Origin-strip シムによって処理され、127.0.0.1:port / localhost:port / [::1]:port / host.docker.internal:port または正確にバインドされたループバックアドレスとポートに対して Origin ヘッダーを削除します。また、ブラウザがデフォルトポートに対して送信するスキーム一致のポートなし形式も受け入れます: ポート 80 では http://host、ポート 443 では https://host です。これらのリクエストは --allow-origin の設定に関係なく通過します。オペレーターは Web Shell を動作させるためにデーモンの自身のポートをリストする必要はありません。

一般的なエラー形状

5xx レスポンスには、存在する場合元のエラーの code と data が含まれます（JSON-RPC スタイル — ACP SDK はエージェントから {code, message, data} を転送します）:

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

リクエストボディ内の不正な JSON は以下を返します:

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

ステータス 400 で。

不明なセッション ID に対する SessionNotFoundError は以下を返します:

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

ステータス 404 で。同時クローズは code: "session_closing" を使用します。

cwd が登録済みワークスペースに正規化されない POST /session に対する WorkspaceMismatchError は、以下とともに 400 を返します:

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

これを事前検出に使用してください: /capabilities から workspaceCwd を読み取り、POST /session から cwd を省略します（プライマリワークスペースにフォールバックします）。または multi_workspace_sessions がアドバタイズされている場合は workspaces[].cwd のいずれかを選択します。

デーモンの --max-sessions 上限を超えた POST /session は、Retry-After: 5 ヘッダーと以下とともに 503 を返します:

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

有効なデーモン全体の合計上限が新しいセッションを拒否する場合 — --max-total-sessions、または limits.maxTotalSessions の下に説明されているデフォルト — 同じレスポンス形状が "scope": "total" とともに返されます。

既存セッションへのアタッチは上限にカウントされないため、アイドル状態のデーモンの再接続は容量限界時でも動作し続けます。

ACP チャネル初期化予算が newSession のディスパッチ前に期限切れになる場合、POST /session は Retry-After: 5 と以下とともに 504 を返します:

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

timeoutMs — および error の数値サフィックス — はデーモンの設定済み --initialize-timeout-ms 予算を反映します（上記の値はデフォルトです）。上記の完全な安全再試行形状は、チャネル初期化が永続的変更に先行する単純なセッション作成の場合のみ出力されます。そのパスでは、初期化が ACP newSession リクエストに先行するため sideEffectPossible: false フィールドが権威を持ち、この構造化契約を理解するクライアントは重複セッションのリスクなくアドバタイズされた遅延後に再試行できます。

branch または worktree を伴うリクエスト、および単純な作成以外のミューテーションを含むルートによって生じる初期化タイムアウト（例えば、コミット済みのフォークが失敗したハンドシェイクより長く存続しうる POST /session/:id/branch や POST /session/:id/side-task など）は、同じ 504 を code: "init_timeout"、phase、および timeoutMs とともに返しますが、Retry-After、retryable、または sideEffectPossible は含みません。これらの場合、ミューテーションの結果は不明です：ブランチとワークツリーの準備はチャネルの初期化前に git を変更するため、失敗時に試行されるロールバックはベストエフォートであり（チェックアウトのロールバックに失敗するとワークスペースは新しいブランチに残り、再試行でブランチが既に存在する競合が発生する可能性があります）、すべての 5xx ミューテーション応答を曖昧として分類するクライアントは保守的にフェイルクローズのままとなり、縮小された形状にも同じポリシーを適用すべきです。POST /session/:id/load と POST /session/:id/resume は、復元リクエストがディスパッチされる前（ensureChannel ステージ）にチャネル初期化がタイムアウトした場合、同じ縮小された init_timeout 504 を生じます。それらの Errors リストに記載されている session_restore_timeout 504 とは異なり、この形状には Retry-After なし、retryable なし、そして復元がディスパッチされなかったためフェンスもインストールされません。POST /session における newSession ディスパッチタイムアウトは例外です：これは 504 を code: "init_timeout"、retryable: true、および予算から導出された Retry-After とともに返しますが、phase や sideEffectPossible は含まれません。なぜなら作成結果が曖昧だからです。他のすべてのタイムアウトラベルは汎用マッピングを維持します。

RestoreInProgressError — 他の登録がその ID を既に所有している場合に POST /session/:id/load、POST /session/:id/resume、または呼び出し元提供 ID の POST /session によって生成されます — 409 と以下を返します：

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

ID が既に進行中の session/resume を持っている場合（またはその逆の場合）、または呼び出し元提供 ID のスポンがどちらかの復元方向と競合する場合に session/load が発行されると発生します。少なくとも Retry-After 秒待ってから再試行してください。同じアクション間の競合（load vs load、resume vs resume）は、復元がアクティブな間はエラーとする代わりに結合されます。

reason はこのコードを共有する 2 つのフェンスを区別し、Retry-After ヘッダーがそれを追跡します：

公開復元リクエストは limits.sessionRestoreTimeoutMs（デフォルト 60 秒）によって管理されます。504 の後、遅延した ACP リクエストとクリーンアップが完了するまで ID はフェンスされたままとなるため、通常の 5 秒間隔で再試行を続けるクライアントはクリアできない 409 に対してスピンすることになります。awaiting_abandoned_cleanup とともに提供される予算から導出されたヒントに従ってください。

SessionWorkspaceConflictError — リクエストされた cwd が登録済みワークスペース 1 つを対象としているにもかかわらず、同じセッション ID が別のランタイムによって既にライブであるか復元中の場合に POST /session/:id/load と POST /session/:id/resume によって生成されます — 以下とともに 409 を返します：

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

クライアントは所有ワークスペースで再試行するか、異なるワークスペースに ID を復元する前に進行中の復元が完了するのを待つべきです。同じワークスペース内の復元競合は引き続きブリッジの restore_in_progress / 結合動作を使用します。

SessionArchivedError は、JSONL が chats/archive/ 下にあるセッションを読み込みまたは再開しようとしたときに生成されます：

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

ステータス 409 で。

SessionArchivingError は、同じ ID に対するセッションアーカイブまたはアーカイブ解除の遷移が既に進行中のときに生成されます：

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

ステータス 409 と Retry-After: 5 で。

機能

デーモンは、serve 機能レジストリからサポートされている機能タグを通知します。クライアントは UI の制御を mode ではなく features で 必ず ゲートする必要があります（設計書 §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']

条件付きタグは、そのデプロイメントまたはランタイム可用性条件が満たされた場合のみ表示されます（以下の表を参照）。F3 の permission_mediation タグは常にオンであり、SDK クライアントがビルドでサポートされるセットを内省できるように modes: ['first-responder', 'designated', 'consensus', 'local-only'] を伴います。ランタイムアクティブ戦略は body.policy.permission にあります。

session_startup_config は、通常およびスタンドアロン作成でのオプションの startupConfig: { modelServiceId, reasoningEffort? } を広告します。このタグを必ずプリフライトしてください：古い通常作成ルートはオブジェクトを黙って無視する場合があります。modelServiceId は必須です（1～256 文字）；reasoningEffort は、選択されたモデルがサポートする場合、none、default、low、medium、high、xhigh、または max を受け入れます。省略時はモデルのみが適用され、推論セッターや暗黙的な default はありません。このオブジェクトはレガシーのトップレベル modelServiceId や明示的な単一スコープと組み合わせることはできず、新しいスレッドを示唆します。起動時には共有デフォルトは保存されません；後のセッション動作は変わりません。

成功には modelApplied: true と startupConfigApplied: { modelServiceId, reasoningEffort?, effectiveReasoning? } が含まれます。モデルセレクターは正規化されています。明示的な推論リクエストのみが 2 つの推論フィールドを含みます；有効な状態は { state: 'disabled' }、{ state: 'provider-default' }、または { state: 'enabled', effort? } です（トグルのみの推論には effort がありません）。無効な構造は 400 invalid_startup_config です；拒否または未確認の選択は 422 startup_config_rejected です。確定的なスタンドアロン拒否は、所有する記録をロールバックし、空の出力ディレクトリの破棄を試みた後に返却します；削除を確認できない記録ロールバックと過渡的な起動失敗は standalone_creation_outcome_unknown を保持しますが、ディレクトリ破棄の失敗はログに記録されるのみで、確定的な拒否は依然として返却されます。SDK における成功ボディの確認失敗はプロトコルエラーであり、回復したセッションを採用するための指示ではありません。

session_scope_override は、POST /session 上のリクエストごとの sessionScope フィールドのネゴシエーションハンドルです（以下を参照）。古いデーモンはこのフィールドを黙って無視するため、SDK クライアントはこのフィールドを送信する前にこのタグについて caps.features をプリフライトすべきです。

session_id_override は、POST /session および ACP session/new メタデータにおけるオプションの呼び出し元提供 sessionId のネゴシエーションハンドルです。クライアントは、古いデーモンがこのフィールドを黙って無視する可能性があるため、このフィールドを送信する前に caps.features にこのタグが含まれていることを確認しなければなりません。

persistent_workspace_registration は、ランタイム時に追加されたワークスペースに対する永続的登録を広告します。POST /workspaces は { "cwd": "/absolute/path", "persist": true } を受け入れ、成功には persisted: true が含まれます。登録はユーザーの Qwen ホーム下のデーモンの正規主ワークスペースにスコープされ、次回のデーモン起動時に復元されます。persist を省略するとプロセスローカル登録が保持されます。GET /workspace-registrations は保存された希望セットを一覧表示し、DELETE /workspace-registrations/:id はアクティブなランタイムをホット除去せずに次回再起動のためのエントリーを忘れます。

workspace_display_name は、POST /workspaces へのオプションの displayName 入力、PATCH /workspaces/:workspace を通じたワークスペースメタデータ更新、およびワークスペースプロジェクション内のオプションの表示名フィールドを広告します。名前は検索やルーティングに関与しません：id と正規 cwd が唯一のセレクターとして残り、重複名が許可されます。

workspace_runtime_removal は DELETE /workspaces/:workspace を介して同期ホット除去を通知します。Capability workspace エントリにはオプションの removable が追加されます。除去できるのは removable: true を持つ行のみです。除去により、ランタイムの永続的な登録エイリアスはすべて破棄されますが、ファイル、設定、トランスクリプト、アーカイブは削除されません。

workspace_runtime は GET /workspace/runtime/status、POST /workspace/runtime/ensure、およびそれらの /workspaces/:workspace/runtime/... 相当を通知します。ensure は capability の選択を受け付けません。これは、選択された信頼できるワークスペースの ACP ランタイムを開始または再利用し、そのライフサイクル状態と単調増加するランタイムエポックを返します。プライマリルートはプライマリライトタイムのみが所有します。修飾付きルートは、選択された登録済みランタイムのみを解決し、フォールバックすることはありません。ensure が成功すると、ランタイムの 10 分間の keepalive ウィンドウが更新されます。ステータスは読み取り専用であり、子プロセスを開始することはありません。並行する ensure は 1 つの物理的な起動を共有します。起動中または失敗時は、再試行可能な 503 runtime_still_starting または 503 runtime_initialization_failed が返されます。capability の準備は、ensure の観測予算が期限切れになった後も継続される場合があります。その場合、ensure は依然としてライブランタイムを返し、ステータスポーリング用に非 ready な capability 状態を示します。この capability は、すべてのアクティブなランタイムブリッジが権威あるライフサイクルスナップショットを提供する場合にのみ通知されます。選択されたレガシー注入ブリッジは、推測された状態やエポックの代わりに 501 workspace_runtime_not_supported を返します。

workspace_runtime_stop は、ユーザー確認済みのランタイム停止を独立して通知します。GET /workspaces/runtime-stop-options は読み取り専用のプロセスグローバルプレビューであり、コミットされた子プロセス数、モデル化された子プロセス上限、各可視ワークスペースのセッション、ブロック理由、チャネル ID、エポック、現在の停止トークン、最新の領収書を含みます。通常のロード済みセッションは明示的に停止できますが、独立した ACP クライアント、有効なスケジュール、保留中のスケジューラー/管理/開始作業、メモリタスク、ワーカー、音声、特殊目的ランタイムはブロックされます。POST /workspaces/:workspace/runtime/stop は厳格な変更ゲートを使用し、選択された信頼できるランタイムのみを対象とします。プレビューから confirmInterruptions: true、expectedChannelId、expectedRuntimeEpoch、expectedStopToken および正確な expectedSessionIds を送信してください。プライマリライトタイムへのフォールバックは絶対に行わないでください。プレビューとすべての領収書には、ランタイムのライブ ACP チャネルが channels（channelId、runtimeEpoch、オプションの executionEngine）としてリストされます。ランタイムは実行エンジンごとに 1 つのチャネルを持つことができ、停止操作はそれらすべてをカバーします。channelId は最初にリストされたチャネルを指し、runtimeEpoch は最後にリストされたエポックであるため、プレビュー後に開始されたチャネルがあると確認情報が古くなります。

応答が成功した場合、承認されたセッションクローズと、リストされたすべての子プロセスのプロセスレジストリ解放の後、state: "stopped"、stopped: true、released: true が含まれます。登録、ファイル、保存された履歴は保持されます。応答には、影響を受けたセッション ID、中断されたセッション ID、クローズされたセッション ID、残りのセッション ID が含まれます。古いまたはブロックされた確認情報は HTTP 409（workspace_runtime_stop_stale / workspace_runtime_stop_blocked）です。部分的なクローズは 409 workspace_runtime_stop_incomplete です。進行中のティアダウン、または解放が証明されていない失敗したティアダウンは 503 workspace_runtime_stop_in_progress / workspace_runtime_stop_failed です。サポートされていない管理操作は 501 workspace_runtime_stop_not_supported です。後でレジストリ解放が証明されたクリーンでないティアダウンは、エラー警告付きで 200 を返す場合があります。未確認のセッションフラッシュは、依然として部分結果/エラー結果を返します。観測/クローズの総予算は 60 秒です。セッションクローズがまだ実行中に予算が期限切れになった場合、応答は state: "failed" と 503 workspace_runtime_stop_failed で確定し、クリーンアップは別個に継続されます。呼び出し元が失敗を受信したとしても、選択されたワークスペースは分離されたままになり、実際のクリーンアップ完了までその子プロセスはカウントされ続けます。読み取り専用オプションは、承認されたクローズと証明された解放の後に stopped を報告するか、永続化が未確認の場合に incomplete を報告することがあります。すでに返された失敗スナップショットは変化しません。セッションクローズの間で予算が使い果たされた場合、応答は state: "incomplete" と 409 workspace_runtime_stop_incomplete で確定します。これ以上クローズや強制キルは開始されず、停止のアドミッションガードは解放されます（生存している子プロセスは通常どおりカウントされ続けます）。残りのセッションを停止するには、新しいプレビューと確認情報が必要になります。フラッシュ拒否は、残りのセッションを強制キルすることで回避できません。ルート終了やグローバルプロセス数の減少だけでは、選択された子プロセスの解放は確立されません。Windows では、レジストリが子孫プロセスグループを追跡しないため、ルートの確定した終了が解放の証拠となります。したがって、released: true はそこではプロセスツリーが消滅したことを証明しません。

最後に消費されたトークンの繰り返し確認により、同じ操作が観測されます。新しい確認情報により、不完全な停止を再試行でき、トークンはローテーションされます。その後、以前に消費された古いトークンは無効になります。応答が失われた場合、別のターゲットを停止するのではなく、オプションを読み取り、ワークスペースと停止トークンによって最新の領収書を照合してください。領収書は、除去、信頼関係の変更、デーモン/ブリッジの再作成後に利用できなくなる場合があります。存在しない場合は結果が不明となり、継続を許可することはありません。SDK の runtimeStopOptions() と workspaceById(id).stopRuntime(confirmation) は、ACP トランスポートを使用していても REST を使用し、POST を自動的に繰り返すことはありません。セッションサブスクライバーは、reason: "client_close" と cause: "workspace_runtime_stop" を含む session_closed を受信します。致命的な停止関連の終了は、さらに persistenceUnconfirmed: true をマークします。更新された Web Shell クライアントは、保存された選択/トランスクリプトを保持し、明示的な Resume を待ちます。これは永続的なサスペンションではなく、一度限りの停止です。イベントを見逃したクライアントは、容量を再び競う可能性があります。

ランタイムステータスと ensure 応答はこの形式を使用します:

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

ワークスペースランタイムに複数の実行エンジンがある場合、runtimeLive と runtimeEpoch はワークスペース制御（MCP と Skills）を提供するチャネルを記述します。そのチャネルがライブである間、他のエンジンの開始または終了によってそれらは変化しません。state は、そのチャネルがライブでない場合、それを cold、starting、または stopping として報告します。active と idle はすべてのエンジンでの作業をカウントします。

capabilities.skills.state は not_started、starting、ready、stale、または error です。失敗時には capabilities.skills.error に {code, message} が含まれます。Skills カタログは、トップレベルと capability の runtimeEpoch 値が一致する場合にのみ最新の状態です。revision は 1 つのランタイムエポック内で Skills の準備順序を示し、エポック間で比較してはいけません。

workspace_skills_config_runtime は、/workspace/{config,runtime}/skills と /workspaces/:workspace/{config,runtime}/skills の下で分割された Skills 読み取りと設定変更を通知します。Web Shell は、Skills 管理のためにこれらのルートを使用し、新しいセッションを作成する際に、一致するエポックのランタイムカタログで置き換える直前に、設定からスラッシュコマンドを埋めるために使用します。この機能が存在しない場合、クライアントはレガシー Skills ルートを引き続き使用する必要があり、Skills のためだけにランタイム ensure を呼び出してはいけません。

session_load と session_resume は、明示的な復元ルート（POST /session/:id/load と POST /session/:id/resume）を通知します。古いデーモンはこれらのパスに対して 404 を返すため、SDK クライアントは呼び出す前に caps.features をプリフライトすべきです。unstable_session_resume は、基盤となる ACP メソッドが connection.unstable_resumeSession と呼ばれていた時期に出荷された SDK との互換性のため、非推奨のエイリアスとして引き続き通知されます。新しいクライアントは session_resume でゲート処理を行うべきです。

limits.sessionRestoreTimeoutMs が存在する場合、これは基盤となる ACP loadSession / unstable_resumeSession リクエストに対するデーモンの実時間予算です。これは v1 で追加されたフィールドです。TypeScript SDK はクライアント側に 10 秒の余裕を持たせ、Web Shell のウォッチドッグは 15 秒の余裕を持たせます。古いバージョンのデーモンと通信するクライアントは、それぞれ 70 秒と 75 秒を使用すべきです。

session_transcript は GET /session/:id/transcript を広告します。これは永続化されたアクティブセッションの JSONL に対する読み取り専用でページング可能な再生ビューです。これは /load とは異なります。クライアントをアタッチせず、ライブ EventBus にシードせず、ライブセッションを作成せず、ライブ再生ウィンドウを変更しません。クライアントは、長いセッションに対して完全なディスク上のトランスクリプトが必要な場合にこれを使用し、コールド UI 復元中の制限付きライブ再生には /load のみを引き続き使用してください。

workspace_persisted_transcript は GET /workspaces/:workspace/session/:id/transcript を広告します。これはデーモンローカルで永続化のみを対象とするページャであり、ACP を起動せず、ライブブリッジ状態を照会せず、設定を読み込まず、プロジェクト機能を検出せず、レガシーな永続化カーソルキーを作成しません。信頼できる単一ワークスペースプライマリが複数形ルートを使用できるため、このタグは無条件です。ワークスペースごとの信頼性認可はすべてのリクエストで引き続き評価されます。登録された信頼できないセカンダリワークスペースは読み取り可能ですが、信頼できないプライマリは拒否されたままです。

workspace_session_export は GET /workspaces/:workspace/session/:id/export を広告します。これは選択されたワークスペースのアクティブな永続化セッションに対する信頼限定の完全エクスポートです。これは session_export および workspace_qualified_rest_core とは独立しています。リリース済みのデーモンは両方の古いタグを広告できますが、複数形ルートを実装していない場合があるため、クライアントはこのタグを直接プリフライトする必要があります。信頼できる単一ワークスペースプライマリは ID または cwd によってルートを使用できるため、このタグは無条件です。エクスポートはライブオーナーを解決せず、ACP を起動せず、クライアントをアタッチせず、他のワークスペースへのフォールバックを行いません。

workspace_archived_session_export は GET /workspaces/:workspace/session/:id/archive/export を広告します。これは選択されたワークスペースのアーカイブ済み永続化ストレージからの信頼限定の完全エクスポートです。これは workspace_session_export および workspace_qualified_rest_core とは独立しており、クライアントはこのタグを直接プリフライトする必要があります。異なるルートが存在することで、古いデーモンがアーカイブの意図を無視して同じ ID のアクティブなトランスクリプトを返すことを防ぎます。

workspace_session_live_state は GET /workspaces/:workspace/sessions/live-state を広告します。これは選択されたワークスペースランタイムのライブセッションおよびメモリ内カタログバージョンの信頼限定かつメモリ専用のスナップショットであり、クライアントに完全な永続化カタログのリロードがいつ正当であるかを通知します。これは workspace_qualified_rest_core とは独立しています。リリース済みのデーモンはより広範なワークスペース REST 機能を広告できますが、このルートを実装していない場合があるため、クライアントはこのタグを直接プリフライトする必要があります。信頼できる単一ワークスペースプライマリは ID または cwd によってルートを使用できるため、このタグは無条件です。ワークスペースごとの信頼性チェックはすべてのリクエストで引き続き適用され、このルートは寛容な信頼できないセカンダリの永続化カタログ読み取りポリシーをライブブリッジ状態に拡張しません。このタグはエンドポイントが存在することを意味しますが、すべてのライブ項目がオプションの updatedAt アクティビティウォーターマークを持つことを保証するものではありません。これはライフサイクルに依存します。

workspace_session_live_state_batch は POST /sessions/live-state を広告します。クライアントはバッチポーリングの前に一度だけこれをプリフライトし、古いデーモンに対しては単一ワークスペースルートを保持します。バッチは単一ワークスペースルートと同じ信頼限定、メモリ専用スナップショットおよびカタログバージョンの意味論を使用します。

オプションのトップレベルフィールド /capabilities sessionLiveStatePollIntervalMs は、ミリ秒単位のデーモン全体のライブ状態ポーリング間隔を広告します。これはワークスペース環境オーバーレイとは独立して、起動環境変数 QWEN_SESSION_LIVE_STATE_POLL_INTERVAL_MS から一度だけ解決されます。1000 から 2147483647 までの整数値が受け入れられます。欠落または無効な値の場合は 5000 が使用されます。Web Shell はすべてのワークスペースライブ状態ポーリングでこのヒントを消費し、古いまたは互換性のないデーモンからフィールドが欠落または無効な場合にも 5000 にフォールバックします。このフィールドは、ルートのスナップショット意味論、即時のローカル/可視性リフレッシュ、または完全カタログポーリングを変更しません。SDK クライアントは独自のタイマーに対する責任を引き続き持ちます。

slow_client_warning は SSE バックプレッシャー動作をカバーします: (a) デーモンは、サブスクライバーのライブフレームバックログまたはライブシリアライズバイトバックログが 75% 以上になったときに、オーバーフローエピソードごとに一度だけ slow_client_warning 合成イベントストリームフレームを発行します（両方の測定値が 37.5% 未満まで排水された後に再武装されます）; (b) GET /session/:id/events は、大きな再生リングに対するコールド再接続時にサブスクライバーごとのフレームバックログを事前サイズ指定するための ?maxQueued=N クエリパラメータ（範囲 [16, 2048]）を受け入れます。シリアライズバイト上限はデーモン所有です（デフォルトではサブスクライバーあたり 2 MiB）、ライブ専用であり、意図的にクエリパラメータがありません。デーモン全体のリングサイズは --event-ring-size によって制御されます（デフォルト 8000、#3803 §02 参照）。古いデーモンは警告/クエリ動作を黙って欠如しているため、オプトインする前にこのタグをプリフライトしてください。

typed_event_schema は SDK の KnownDaemonEvent スキーマと一致するデーモンイベントペイロードを広告します。古いデーモンは依然として互換性のあるフレームをストリーミングする可能性がありますが、SDK クライアントは型付きイベントカバレッジを想定する前にこのタグをプリフライトすべきです。

client_heartbeat は POST /session/:id/heartbeat を広告します。古いデーモンは 404 を返します。周期的なハートビートを発行する前にこのタグをプリフライトしてください。

session_close および session_metadata は DELETE /session/:id および PATCH /session/:id/metadata を広告します。古いデーモンは 404 を返します。閉じるまたは名前変更のアフォーダンスを公開する前にこれらのタグをプリフライトしてください。

session_organization はカスタムセッショングループおよびピン留めを広告します。これは GET/POST/PATCH/DELETE /workspace/:id/session-groups、PATCH /session/:id/organization、およびオプトインの整理されたリストビュー GET /workspace/:id/sessions?view=organized を追加します。session_organization と workspace_qualified_rest_core の両方が広告されている場合、ワークスペース修飾付きの組織ミューテーション PATCH /workspaces/:workspace/session/:id/organization も利用可能です。レガシーなミューテーションはプライマリワークスペース専用として残ります。古いデーモンはミューテーション/グループルートに対して 404 を返し、整理されたビュー契約を無視するため、WebShell/SDK クライアントは対応するグループ化またはピン留め UI を表示する前にこれらのタグをプリフライトする必要があります。

session_archive は v1 ディレクトリ状態アーカイブ API を広告します: POST /sessions/archive、POST /sessions/unarchive、および GET /workspace/:id/sessions?archiveState=active|archived。アーカイブされたセッションは、アーカイブ解除されるまで読み込みまたは再開できません。session_archive_idle_guard は追加的な requireIdle アーカイブオプションを広告します: オーニングランタイムは、クローズを開始する直前にアクティブな作業がアイドルであることを確認し、そうでない場合はアクティブなトランスクリプトをそのまま残します。session_storage_conflict_repair は追加的な resolveConflicts リクエストオプションおよび以下に記載される resolvedConflicts レスポンスバケットを広告します。

workspace_qualified_rest_core は /workspaces/:workspace/... の下に複数のコア REST ルートを公開します。セレクターは、まず正確なワークスペース ID として解決され、次に正規化後の URL エンコードされた絶対 cwd として解決されます。新しい単一ワークスペースのデーモンには、multi_workspace_sessions が存在しない場合でもプライマリランタイムが workspaces[] に含まれており、クライアントはワークスペース修飾ルートに必要な ID を検出できます。クライアントは配列を省略する古いデーモンのために capabilities.workspaceCwd にフォールバックする必要があります。信頼ステータスと信頼リクエストルートは、登録済みで信頼されていないワークスペースで利用可能です。修飾付きフックステータス読み取り（GET /workspaces/:workspace/hooks）も、保留中のプロジェクトフックの信頼決定を報告するため、登録済みで信頼されていないワークスペースに対して提供され、修飾付き承認ミューテーションと一致します。ファイル読み取りルートは既存のファイルシステム読み取りポリシーに従います。登録済みで信頼されていないセカンダリワークスペースも、永続化専用のセッションおよびセッショングループカタログを公開します。これらの読み取り操作はセッションにアタッチせず、ACP を開始せず、ライブブリッジ状態をマージしません。ファイル書き込み、カタログミューテーション、およびその他の複数のコアルートは、より狭いポリシーを文書化する個別の機能がない限り、信頼されたワークスペースを必要とします。workspace_persisted_transcript（読み取り専用）、または信頼付与ミューテーションは、workspace_trust_grant が公開されているかどうかに関係なく、登録済みで信頼されていないワークスペースに対して受け入れられます。このタグは信頼ホットリロードが接続されているかどうのみを報告するため、記録された決定はデーモンの再起動なしで実行中のランタイムに到達できます。ただし、ルートが提供されているかどうかは決して報告しません。信頼されていないプライマリは、複数のカタログおよびトランスクリプトルートから引き続き 403 { code: "untrusted_workspace" } を受け取ります。レガシーな単数形のプライマルルートは、既存の互換性動作を維持します。このタグは、コアファイル、ステータス、設定、権限、信頼、ライフサイクル、MCP 制御、ツールおよびスキル切り替え、メモリ、ワークスペースエージェント CRUD、およびセッションストレージのサーフェスをカバーします。認証、音声、拡張機能、ACP/WebSocket トランスポート、チャネルワーカールーティング、またはワークスペース修飾付きセッションエクスポートはカバーしません。事前に workspace_session_export または workspace_archived_session_export を確認してください。ワークスペース信頼は ACL ではありません。デーモントークンを保持するクライアントは、このポリシーによって許可されるすべての登録済みワークスペースサーフェスを読み取ることができます。

workspace_qualified_voice は、信頼されたワークスペースランタイムによって選択された Voice ルートを公開します。具体的には GET と POST /workspaces/:workspace/voice、POST /workspaces/:workspace/voice/transcribe、および WS /workspaces/:workspace/voice/stream です。これは、マルチワークスペースランタイムと共有 ACP/Voice WebSocket リスナーの両方が有効な場合にのみ公開されます。セレクターは、他の複数のルートと同じ ID またはエンコードされた絶対 cwd のルールに従います。REST では、不明なセレクターは 400 { code: "workspace_mismatch" } を返し、信頼されていないセレクターは 403 { code: "untrusted_workspace" } を返します。WebSocket アップグレード拒否は、構造化された JSON エンベロープなしで対応する HTTP 400/403 ステータスを公開します。どちらのトランスポートもプライマリにフォールバックしません。レガシーな /workspace/voice、/workspace/voice/transcribe、および /voice/stream はプライマリ専用です。クライアントはすべての修飾付き Voice モダリティのために workspace_qualified_voice を使用し、選択されたランタイムに構成固有のエラーを報告させます。レガシーな workspace_voice、workspace_voice_transcription、および voice_transcribe タグは、プライマリにバインドされたルートのみを記述しており、修飾付きセカンダリ構成を隠蔽してはいけません。

workspace_qualified_memory は、ワークスペース修飾付き管理メモリルートである POST /workspaces/:workspace/memory/{remember,forget,dream}（タスクの投入）と GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId（それらの読み戻し）を公開します。これは、ACP HTTP とマルチワークスペースランタイムの両方が有効な場合にのみ公開されます。セレクターは、他の複数のルートと同じ ID またはエンコードされた絶対 cwd のルールに従います。各登録済みワークスペースには独自のタスクレーンがあり、プライマリの修飾付きレーンは単数形の /workspace/memory サーフェスと同じインスタンスであるため、片方に投入されたタスクはもう片方で読み取れます。解決は厳密に選択されたランタイムごとに行われ、プライマリへのフォールバックはありません。不明なセレクターは 400 { code: "workspace_mismatch" } を返し、信頼されていないセレクターは 403 { code: "untrusted_workspace" } を返し、非アクティブまたはドレイン中のランタイムは 503 { code: "workspace_runtime_unavailable" } を返します。読み取り操作はレーンを割り当てないため、タスクのないワークスペースをポーリングすると 404 { code: "<kind>_task_not_found" } が返されます。タスク ID はそのレーンにスコープされており、ワークスペース再構成やランタイム置換を生き延びません。古い ID はデータ損失条件ではなく 404 を返します。ACP HTTP が無効な場合、タグは公開されず、非プライマリ修飾付きリクエストは再試行不可の 501 { code: "workspace_memory_unavailable" } を返しますが、プライマリ修飾付きルートはローカル所有のレーンを通じて動作を継続します。

session_lsp は、デーモンクライアント向けの読み取り専用構造化 LSP ステータススナップショットである GET /session/:id/lsp を公開します。古いデーモンは 404 を返します。リモート LSP ステータスを公開する前にこのタグを確認してください。

session_resources は、選択されたライブセッションの Config から構築された、サニタイズされた Skill および MCP スナップショットの読み取り専用ペアである GET /session/:id/resources を公開します。ルートはライブセッション所有者のスコープであり、プライマリランタイムにフォールバックせず、ワークスペースステータスからセッションのリソースを推測しません。ネストされた skills および mcp オブジェクトは、対応するワークスペースステータスペイロードを再利用しますが、MCP 認証、プール、ワークスペース予算、およびワークスペース検出エラーのエンリッチメントを省略します。選択されたセッションの MCP マネージャーによって報告されるステータス、検出、および会計情報はそのまま残ります。古いデーモンは 404 を返します。セッションリソースカタログを表示する前にこのタグを確認してください。

session_status は、ID による単一セッションのライブブリッジサマリーである GET /session/:id/status を公開します。clientCount および hasActivePrompt に加えて、ライブセッションは isWaitingForPermission、isWaitingForUserQuestion、pendingInteractionCount、および失敗したターン後の保持された turnError を公開します。エラーは次のプロンプトが実際に開始されたときにクリアされます。現在のブリッジ内で実行中のターンを決着させたライブセッションには、ライブステートルートの下で文書化されている同じアクティビティウォーターマークである updatedAt も含まれます。このルートはブリッジサマリーを直接返すため、値は永続化されたトランスクリプト mtime とマージされず、セッションリストが報告するものより早くなる可能性があります。単一セッションステータスレスポンスとワークスペースセッションリストの両方に turnError と pendingInteractions が含まれます。これらは、レンダリング準備完了の権限アクションまたは ask_user_question 質問に加え、既存の権限投票ルートで必要な requestId と選択可能なオプションです。各ユーザー質問には answerKey があります。その値をキーとして answers で投票します。例：{ "0": "Polling" }。永続化専用のセッションは、ランタイムが存在しないためランタイム状態を省略します。古いデーモンは 404 を返します。完全なセッションリストをスキャンする代わりに単一セッションのステータスをポーリングする前にこのタグを確認してください。

session_info は GET /workspace/:id/session-info とその /workspaces/:workspace/session-info ツインを公開します。レスポンスは、リストメタデータをハイドレートせずに、永続化されたアクティブおよびアーカイブされたセッション数を集約します。これは明示的な O(n) ディスクスキャンであり、ポーリングしてはいけません。クライアントは truncated: true を下限結果として扱う必要があります。

session_approval_mode_control、workspace_tool_toggle、workspace_skill_settings_toggle、workspace_skill_settings_batch_toggle、extension_batch_activation_v2、workspace_init、および workspace_mcp_restart は、以下に記載されているミューテーション制御ルートをアドバタイズします。承認モード制御は非厳密互換性ゲートを維持します。その他の制御はオペレーター権限によって厳密にゲートされます：信頼できるループバックプライマリ、ベアラー認証済み、またはペアリングされたローカル制御リクエストが通過します。信頼できるループバック権限なしで厳密ゲートに到達したトークンレスのプライマリリクエストは 401 token_required を返します。設定された資格情報の欠落または無効、および未ペアリングのローカル制御資格情報は、ベアラーミドルウェアによって事前に拒否され、プレーンな 401 Unauthorized が返されます。これらのルートのいずれかが欠けているデーモンは 404 を返します。設定固有の Skill タグは異なります：退役タグ世代からのデーモンは workspace_skill_toggle と workspace_skill_batch_toggle をアドバタイズし、同じパスでカタログ検証済みのコントラクトを提供します。退役した単一ターゲットルートは HTTP 404 skill_not_found または 409 skill_not_toggleable を返す可能性があります。退役したバッチルートは HTTP 200 を返し、カタログ由来の失敗を errors[] に配置します。そのアフォーダンスを公開する前に各タグをプリフライトし、ルート到達可能性のプロビングによって設定固有の Skill コントラクトを推測しないでください。ルートパスとリクエストボディは変更されていません。

mcp_guardrails（issue #4175  PR 14）は MCP バジェットサーフェスをカバーします：GET /workspace/mcp の clientCount / clientBudget / budgetMode / budgets[] フィールド、サーバーごとのセルの disabledReason フィールド、および --mcp-client-budget / --mcp-budget-mode CLI フラグ。古いデーモンは新しいフィールドを完全に省略します。SDK クライアントは budgets[] セマンティクスに依存する前にこのタグをプリフライトします。レジストリの記述子には将来の機能モード公開用の modes: ['warn', 'enforce'] も含まれていますが、現時点ではクライアントはスナップショットの budgetMode フィールドからモードを推測します。enforce モードでのサーバー拒否は Object.entries(mcpServers) 宣言順序によって決定論的です。将来のスコープ優先度レイヤー（qwen-code が採用する場合）は、claude-code の plugin < user < project < local 慣例を反映するためにこれを「最低優先度が最初」に変更します。

スコープは能力駆動型です。 mcp_workspace_pool を使用すると、1つのワークスペースランタイム内のセッションはトランスポートプールと WorkspaceMcpBudget を共有し、スナップショットは budgets[0].scope: 'workspace' を出力します。異なるワークスペースランタイムは独立したプールを所有します。タグがない場合、各 ACP セッションはレガシーな McpClientManager を使用し、スナップショットは scope: 'session' を出力し、N 個のセッションがそれぞれ設定された上限を消費する可能性があります。

workspace_file_read はテキスト/リスト/統計/glob ワークスペースファイルルート（GET /file, GET /list, GET /glob, GET /stat）をカバーします。workspace_file_bytes は GET /file/bytes をカバーしており、これは後から追加されたもので、クライアントが PR19 時代のデーモンに対して生のバイトウィンドウサポートを事前チェックできるようになります。workspace_file_write はハッシュ対応のテキスト変更ルート（POST /file/write, POST /file/edit）をカバーします。write タグはルート契約が存在することを意味しますが、現在のデプロイメントが匿名による変更を受け入れていることを意味するわけではありません。write/edit は厳格な変更ルートであり、オペレーター権限が必要です。トークンなしの信頼できるループバックもこれに該当します。workspace_file_upload は POST /file/upload、つまりバイナリ入力ルートをカバーしています。MAX_UPLOAD_BYTES (50 MiB) 上限の application/octet-stream ボディがワークスペースに書き込まれますが、上書きは行われず、名前が重複している場合は自動で番号が付与されます（name (1).ext, name (2).ext, …）。これもまた厳格な変更ルートです。

workspace_file_delete は POST /workspaces/:workspace/file/delete のみをカバーします。レガシープライマリ /file/delete ルートは存在しません。JSON ボディは { "path": "relative/file.txt" } であり、成功時は { "kind": "file_delete", "path": "relative/file.txt" } を返します。この厳密なミューテーションルートは、選択された信頼できるローカルワークスペースから1つの通常ファイルを永久的に削除します。ディレクトリとシンボリックリンクは拒否されます。サポートされていないファクトリー（SSH を含む）は 422 を返します。この能力はプロトコルサポートを説明しており、すべてのワークスペースでの削除許可を意味しません。クライアントは workspace_qualified_rest_core もプリフライトする必要があります。

workspace_qualified_rest_core がアドバタイズされると、同じファイルサーフェスは /workspaces/:workspace/file、/workspaces/:workspace/file/bytes、/workspaces/:workspace/stat、/workspaces/:workspace/list、/workspaces/:workspace/glob、/workspaces/:workspace/file/write、/workspaces/:workspace/file/edit、/workspaces/:workspace/file/upload、および /workspaces/:workspace/file/delete でも利用可能になります（最後のルートはさらに workspace_file_delete を必要とします）。

workspace_directory_create と workspace_directory_delete は独立して POST /workspaces/:workspace/directory/create と POST /workspaces/:workspace/directory/delete をアドバタイズします。操作のタグを workspace_qualified_rest_core と一緒にプリフライトしてください。古い適格なデーモンはこれらのルートを欠いている可能性があります。両方とも、プライマリフォールバックやレガシープライマリ対応物を持たない、信頼できるアクティブな選択されたローカルランタイムが所有する厳密なミューテーションです。作成は既存の親の下で排他的です。削除は永久的かつ再帰的です。

同じタグは /workspaces/:workspace/agents と /workspaces/:workspace/agents/:agentType でワークスペース修飾付きプロジェクトエージェント CRUD も公開します。これらの複数形ルートは、選択されたワークスペースのプロジェクトレベルのエージェントのみを読み取ったり変更したりします。global と user スコープリクエストは 400 { code: "global_scope_not_supported_for_workspace_route" } を返します。ワークスペースなしの /workspace/agents ルートは既存のプライマリワークスペース動作を維持し、ユーザーレベルのエージェントスコープに対する唯一の REST サーフェスのままです。

extension_management_v2 は /extensions/* でユーザーレベル拡張カタログとミューテーションサーフェスを、/workspaces/:workspace/extensions/* でワークスペースアクティベーションプロジェクションをアドバタイズします。アーティファクトはグローバルです。ワークスペースルートはプロジェクション読み取り、正確なアクティベーションオーバーライド、およびランタイム更新のみを公開します。読み取りは信頼できない登録済みワークスペースを対象とする場合がありますが、アクティベーション、更新、およびワークスペーススコープ付きインストールは信頼できるターゲットを必要とします。遅いミューテーションは /extensions/operations/:operationId でデーモンローカルな操作を使用します。ストア生成が権威ありであり、操作履歴ではなく、再起動間およびデーモン間で権威があります。公開された workspace_extensions 能力と /workspace/extensions/* ルートはプライマリワークスペース互換性アダプターとして残ります。クライアントは extension_management_v2 をプリフライトする必要があり、デーモンモードや workspace_qualified_rest_core から推測してはいけません。

extension_git_credentials は POST /workspace/extensions/install と POST /extensions/install の両方で認証済み HTTPS Git インストールをアドバタイズします。クライアントは URL ユーザー情報や credentialPersistence を送信する前にこのタグをプリフライトする必要があります。古いデーモンは URL 資格情報を拒否します。このタグはバックエンドプロトコルサポートを説明しており、キーチェーンの利用可能性を説明するものではありません。保存モードは端末操作結果で選択されたバックエンドを報告します。

extension_local_path_install は POST /workspace/extensions/install と POST /extensions/install の両方でデーモンローカルな Extension ソースをアドバタイズします。source はデーモンホスト上に存在する絶対パスでなければなりません。相対パスはサポートされないままであるため、デーモンプロセス cwd がソースアイデンティティを変更したり GitHub owner/repo ショートハンドをシャドーイングしたりすることはできません。既存のインストール操作は Extension を管理ストレージにコピーしますが、ソースをリンクしません。クライアントはこのタグをプリフライトする必要があります。なぜなら古いデーモンはローカルソースを拒否するためです。

extension_batch_activation_v2 は PUT /extensions/activation と PUT /workspaces/:workspace/extensions/activation を追加します。両方とも extensionNames で 1〜100 の名前を受け入れ、大文字小文字を区別せずに重複排除しながら最初に出現した順序を保持し、変更されたターゲットを 1 つの世代で永続化し、1 つの 202 操作ハンドルを返します。enabled または disabled を設定する際に、ターゲットがインストールされている必要はありません。その名前は、その名前の Extension がインストールされたときに保持される望ましい状態の宣言を作成します。グローバルルートは state: "enabled" | "disabled" を受け入れ、V2 defaultActivation に書き込みます。ワークスペースルートも "inherit" を受け入れ、選択された信頼できるランタイムに対して正確なオーバーライドを適用またはクリアします。inherit は不明な名前を宣言せず、すべて不明なクリアは updated: false を報告します。

extension_activation_explicit_refresh は、単一およびバッチのアクティベーション操作が、永続的なポリシーコミット後に直接アクティブセッションを更新することなく完了することを意味します。即時の適用が必要な呼び出し側は、アクティベーションの成功を待ってから、リフレッシュカウントを直接返す同期プライマリワークスペースの POST /workspace/extensions/refresh、または別の操作ハンドルを返す選択されたワークスペースの非同期 POST /workspaces/:workspace/extensions/refresh のいずれかをサブミットする必要があります。この 2 つの形式は互換性がないことに注意してください。非同期操作は、完全なランタイム調整が完了したときに適用された世代を記録しますが、同期ルートは何も記録しないため、世代レコンサイラーはそのワークスペースを保留中とみなし、次のパスでセッションを再度更新します。特定のワークスペースを指定できる呼び出し側は、非同期形式を優先すべきです。リフレッシュ失敗は、アクティベーション結果をロールバックしたりダウングレードしたりしません。この機能を備えていないデーモンは、アクティベーションにランタイムリフレッシュをすでに含んでいるため、互換性のあるクライアントは 2 番目のリフレッシュをサブミットしてはいけません。独立した 30 秒の世代レコンサイラーは有効なままであり、通常は次のパスでコミットされたポリシーを適用します。失敗した調整は、後続のパスで再試行されます。

Extension Management V2 ワイヤ契約

すべてのルートは、上記のデーモンベアラート認証ルールを使用します。X-Qwen-Client-Id は V2 ミューテーションルートではオプションです。提供される場合、ミューテーションのターゲットワークスペースランタイムのいずれかに登録されているクライアントを識別する必要があります。:extensionId は、小文字の 64 進数の拡張機能 ID です。:workspace は、まず正確なワークスペース ID として解決され、それ以外の場合は正規化後の URL エンコードされた絶対 cwd として解決されます。

明示的な Extension リフレッシュ

機能タグ: オプションのセッション選択には workspace_session_refresh。POST /workspace/extensions/refresh (プライマリランタイム) と POST /workspaces/:workspace/extensions/refresh (選択されたランタイム) の両方が次を受け入れます:

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

sessionIds を省略すると、完全なランタイムリフレッシュが維持されます。配列が提供された場合、リクエスト順に重複排除され、[] はセッションやブートストラップキャッシュをリフレッシュしません。ID は空でない文字列である必要があります。無効なリクエスト形状は HTTP 400 を返し、他のワークスペースが所有するセッションを含む不明な ID は、作業開始前に HTTP 404 を返します。セッションの所有権は、解決されたランタイム内でのみチェックされ、プライマリランタイムへのフォールバックはありません。既存の認証、厳格なミューテーション、ワークスペース信頼、およびクライアント ID ゲートが適用されます。

プライマルートは依然として { refreshed, failed } で HTTP 200 を返し、修飾ルートは依然として操作ハンドル付きで HTTP 202 を返します。カウントは選択されたセッションを記述します。sessionIds を使用したリフレッシュは、選択が現在のすべてのセッションをカバーしていても、ワークスペース全体の適用済み世代を進めません。自動の完全調整は変更されず、後で他のセッションをリフレッシュする可能性があります。選択はセッションスコープのアクティベーションポリシーを作成しません。共有ランタイムキャッシュは変更される可能性があり、ワークスペースイベントはワークスペース全体のままです。

クライアントは、空の配列を含めてフィールドを提供する前に workspace_session_refresh をプリフライトする必要があります。古いデーモンはこれを黙って無視する可能性があります。フィールドなしの既存の呼び出しには、新しい機能チェックは不要です。

ワークスペースリソース状態

extension_state を独立してプリフライトします。これは Skills のみをサポートし、MCP リソース管理を意味しません。両方のルートは登録されたワークスペースランタイムを選択し、プライマリにフォールバックすることは決してありません。GET は既存の読み取り専用信頼ルールに従います。PUT は信頼できるワークスペースが必要です。

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

PUT は、単一要素のバッチを含む 1〜100 のエントリを受け入れます。キューイング前に、不正なエントリ、大文字小文字を区別しない重複名、およびサポートされていないグループを拒否します。すべての名前は、現在無効になっている Skills を含む、インストールされたターゲット Extension に属している必要があります。無効なターゲットは、部分的な書き込みなしで操作を失敗させます。1 つのロックされたストアコミットが、正確な正規化されたワークスペースに対するリストされたオーバーライドをマージします。リストされていない Skills と他のワークスペースは保持されます。設定の書き込み、将来の名前の宣言、または親 Extension の暗黙的なアクティベーションはありません。

GET は v: 1, workspaceId, workspaceCwd, extensionId, name および skills を返します。各 Skill には name, defaultEnabled, nullable な workspaceEnabled, effectiveEnabled, およびオプションの disabledReason/lockedScope があります。マニフェストのオプションの skillStates はデフォルトを提供します。値が欠落している場合は、有効がデフォルトになります。アクティブな親の場合、優先順位は、設定によるハード無効化、設定による明示的な有効化、設定によるデフォルト無効化、ワークスペース内部オーバーライド、マニフェストデフォルトです。内部無効化は disabledReason: "default" を使用し、設定をロックすることはありません。無効または削除された親は、Skill オーバーライドによって復活させることはできません。

set_extension_state 操作は順序付けられた result.resourceStates.skills を含む status: "updated" を返します。result.states は更新チェックの意味を保持します。永続化された状態は、すべてのセッションが更新されたことの証明にはなりません。デーモンは、ブートストラップおよびライブセッションを含むターゲットランタイムの Skills とそのコマンド/モデルコンテキストのみを更新し、無関係な MCP/LSP/hooks は再起動しません。コミット後の更新失敗は、状態をロールバックせずに警告を生成します。オーバーライドは再起動と Extension の更新後も存続し、アンインストール時に削除されます。クライアントは、より優先度の高い設定を書き込む Skill settings API にフォールバックしてはなりません。

グローバルカタログ

グローバルカタログのレスポンスは次のとおりです:

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

インストールメタデータが利用できない場合、installType は省略されます。defaultActivation は enabled または disabled です。workspaceOverrideCount は保存された inherit エントリを除外します。

ワークスペースプロジェクションのレスポンスは次のとおりです:

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

継承の場合、workspaceActivation は enabled、disabled、または null です。activationSource は default、workspace_override、legacy_path_rule、または cli_override です。desiredGeneration は永続ストアの世代番号であり、appliedGeneration はコントローラーがそのワークスペースランタイムに適用済みとして記録した最新の世代番号で、一時的に遅延する可能性があります。

インストールには明示的な同意と初期アクティベーションが必要です:

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

ワークスペース限定の初期アクティベーションには { "scope": "workspace", "workspaceId": "target-workspace-id" } を使用します。ターゲットが存在し、信頼されている必要があります。デーモンへのインストールでは GitHub、Git、npm ソースを受け入れます。extension_local_path_install がアドバタイズされている場合、デーモンホスト上に存在する絶対パスも受け入れます。ref は npm には適用されず、ref と autoUpdate はローカルソースには適用されず、registry は npm のみに適用されます。ref、autoUpdate、allowPreRelease、および registry はオプションです。

extension_git_credentials がアドバタイズされている場合、HTTPS Git ソースにはユーザー情報を含めることができます。例えば https://username:token@git.example.com/org/repository.git などです。credentialPersistence はそのようなソースでのみ有効です。これは stored または one_time であり、省略された場合はデフォルトで one_time になります。保存モードでは、デーモンのハイブリッドシークレットストレージを通じて資格情報を保存し、インストールメタデータにはクリーンなリポジトリ URL のみを保持するため、拡張機能は更新可能のままです。一回限りのモードでは、リポジトリ URL も資格情報も保存せず、更新不可能な snapshot を作成します。このモードでは autoUpdate: true は拒否されます。URL 資格情報なしでフィールドを提供する場合、無効な資格情報を提供する場合、または npm、アーカイブ、ローカル、SSH、非 Git ソースで資格情報を使用する場合は、400 が返されます。

資格情報付きのインストールレスポンスと操作では credentialPersistence が公開され、credentialStorage が keychain または encrypted_file として公開される場合があります。一回限りの操作では source は省略されます。保存された操作ではクリーンなソースが返される場合があります。スナップショットカタログ/ステータスエントリではソースが省略され、credentialPersistence は one_time に設定され、not updatable が報告されます。更新は extension_not_updatable で失敗します。利用不可の保存済みシークレットはネットワークアクセス前に extension_credential_unavailable で失敗します。

グローバルおよびワークスペースアクティベーション PUT リクエストは同じボディを使用します:

{ "state": "enabled" }

state は enabled または disabled です。更新、アンインストール、更新チェック、アクティベーションクリア、および更新リクエストには必須のボディはありません。

バッチアクティベーションリクエストでは Extension 名を使用します:

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

ワークスペースバッチでは "state": "inherit" も受け入れます。終端のグローバル結果には name と defaultActivation が含まれ、ワークスペース結果には name、workspaceActivation（継承の場合は null）、および effectiveActivation が含まれます。不正な名前はリクエストを拒否します。既存の Store アイデンティティとの競合は、部分的なコミットなくアトミックに失敗します。不明な inherit ターゲットは永続化されません。オーバーライドのクリアは、デフォルトアクティベーション宣言を作成したり、後続のインストール同意を置き換えたりしてはならないためです。

承認されたすべての非同期変更は次を返します:

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

ワークスペース修飾付きの変更は、同じグローバル /extensions/operations/:operationId ポーリングパスを使用します。操作履歴はプロセスローカルであり、有限数の終端エントリのみを保持し、デーモン再起動時に失われます。クライアントは、操作 ID が消えた場合にカタログまたはワークスペースプロジェクションを再読み込みし、世代番号を比較する必要があります。

操作スナップショットはこの形状をしています:

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

status は queued から running へ遷移し、その後 succeeded、succeeded_with_warnings、または failed へ遷移します。実行中、phase は preparing、committing、または reconciling です。成功時の終端状態には result が含まれる場合があり、status は installed、enabled、disabled、updated、uninstalled、checked、または refreshed と等しくなります。調整結果にはさらに refreshed、failed、および error が含まれる場合があり、バッチアクティベーション結果には順序付けられた results が含まれます。更新チェックは拡張機能名をキーとした result.states を返し、値には checking for updates、update available、up to date、not updatable、または error などが含まれます。資格情報と認証ヘッダーは操作フィールドには決して含まれません。

永続コミットの後に不完全なクリーンアップまたはランタイム調整が発生した場合、失敗した変更として報告されません。代わりに succeeded_with_warnings を返し、コミットされた結果を保持します:

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

警告 workspaceId と code はオプションです。workspaceCwd と error は常に存在します。クライアントは警告を表示し、カタログ/プロジェクションを更新する必要があり、永続的な変更を盲目的に再試行してはなりません。

検証および認可の失敗は、安定したコードが存在する場合は { "error": "...", "code": "..." } を使用する同期的な HTTP エラーです。重要なケースは 400 invalid_extension_id、400 invalid_extension_names、400 invalid_extension_name、400 invalid_extension_activation、400 workspace_mismatch、403 untrusted_workspace、404 extension_operation_not_found、および 429 extension_queue_full です。インストール検証では、無効なソース/参照/レジストリオプション、同意の欠如、または初期アクティベーションの欠如/無効に対して 400 も返されます。202 の後に失敗した変更は、操作履歴に保持されている間、status: "failed"、error、およびオプションの安定した code で表現されます。一般的なコードには extension_prepare_timeout と extension_conflict が含まれます。操作に対する HTTP 404 は、操作履歴が永続的ではないため、ロールバックを意味しません。

daemon_status は GET /daemon/status、つまり以下に文書化されている統合された読み取り専用オペレーター診断スナップショットを通知します。

daemon_update はプロセスグローバルな GET /daemon/update, POST /daemon/update/prepare, POST /daemon/update/restart インターフェースを通知します。

scheduled_task_gate は POST と PATCH /scheduled-tasks におけるオプションの gate、およびタスクビューにおける gate と gateStatus を通知します。ゲートとは、モデルの外側で所有セッションが各発火時に実行するシェルコマンドです。出力ありで exit 0 の場合、その出力を添付して発火が配信されます。stdout が空で exit 0 の場合、スキップされます。非ゼロ終了の場合、すべての発火時ではなく、ゲートが失敗し始めたときに報告されます。gateStatus.lastOutcome は quiet, delivered, failed または blocked です。

• ゲートには繰り返し実行されるタスクが必要です。recurring: false を伴う POST、またはワンショットタスクにゲートを設定するか、ゲート付きタスクをワンショットにする PATCH は、400 gate_requires_recurring を返答します。すでにその状態にあるタスクは、他の編集内容を保持します。不正なゲート（POST で空、コメントのみ、2048 文字を超える、NUL 文字またはペアになっていない UTF-16 サロゲートを含む、bash -c '…' のようなシェルラッパー、または & でバックグラウンド実行されている部分がある場合）は 400 invalid_gate を返答します。& チェックは字句的かつベストエフォートです。不明な場合は拒否され（コメント内の &、ヒアドキュメント本体、または (( … )) など）、これを通過したゲートが、バックグラウンド部分が stdout を保持している状態で stdout が空のまま終了した場合、failed として報告されます（bwrap シェルサンドボックス外では、PID 名前空間によりコマンドとともにその部分が終了します）。PATCH, gate: null または gate: "" では、ゲートとその condition がクリアされます。
• condition によって保護されているレガシータスクは、PATCH 内の任意の gate キーを 409 task_legacy_unsupported で拒否するため、クライアントは変更する場合にのみ gate を送信します。
• これらのルートを通じて書き込まれたゲートには、セッションからの確認はありません。同じコマンドに対する monitor 呼び出しが確認なしで実行される場所でのみ、無人実行されます。具体的には、保存された Monitor(...) または Bash(...) の許可ルール下、読み取り専用コマンドとして、または auto もしくは yolo セッション内です。deny ルールはすべてのモードでブロックし、plan モードでもブロックします。ブロックされた発火は blocked で確定します。
• クライアントはこのタグのないデーモンに gate を送信してはなりません。そのようなデーモンは POST でそれを破棄し、ゲートのみの PATCH に対して 400 empty_patch を返答します。

autofix_pr_watches は GET /autofix-pr/watches（プライマリワークスペース）と GET /workspaces/:workspace/autofix-pr/watches（登録済みで信頼できるワークスペース）を通知します。それぞれがワークスペースのクローンの /autofix-pr ウォッチに対し、qwen autofix-pr status がリスト表示するように応答します。ウォッチのファイルはクローンのメインワークツリー（.qwen/tmp）の下から読み取られ、シンボリックリンクを追わず、ブロッキングせずに開かれます。ロックは取得されず、GitHub には問い合わせず、クローンを見つけるための git worktree list 以外の git コマンドは実行されません。応答は { v: 1, available, root?, now?, watches, unreadable? } です。ワークスペース用の git リポジトリが見つからない場合（または git がそこで実行できない場合）、available は false となり、ウォッチはありません。root はクローンのメインワークツリーであり、1 つのクローンの 2 つのワークスペースで同じ値になります。ウォッチは status（/autofix-pr 設計書のセクション 6.10）のフィールドを持ちますが、thisSession, worktreePath, pushTarget, gitTrusted, worktreeWork は含みません。その session はそれを所有するセッションであり、このデーモンのセッションではない可能性があります。ウォッチの停止はスキルが行います（所有セッション内の /autofix-pr stop <n>）。これらのルートは何も変更しません。

条件付きタグ。 これらの機能タグは、デプロイメントトグル、ランタイムワイヤリング、または可用性条件がアクティブな場合のみ広告されます。タグが存在することは、ドキュメント化された動作が利用可能であることを意味し、存在しないことは、そのタグより前の古いデーモンであるか、その条件が false である現在のデーモンであることを意味します。現在:

Live VoiceはデフォルトですべてのプラットフォームにおいてWeb Shellエンドポイント（realtime_voice_web、WS /live/web）を使用します。ネイティブmacOS Hostはオプトインです：QWEN_SERVE_LIVE_NATIVE_HOST=1 で起動されたmacOSデーモンのみが realtime_voice をアドバタイズし、WS /live/host を登録し、Liveが有効な場合にHostをインストールします。これがない場合、/live/setup は再試行不可の install エラーとともに nativeHost: false を報告し、POST /live/setup/install および POST /live/setup/launch は 409 live_native_host_unavailable に応答します。

ブラウザ Host は、ユーザーがページと画面を共有している間のみ host.capture_visual に応答します。これはページが hello メッセージ内で selfChecks.screenShare として報告します。共有は別個の明示的な操作です。モデルはターン中に要求し、getDisplayMedia にはユーザーのジェスチャーが必要であるため、ページはストリームを保持し、リクエストごとに 1 フレームを取得します。何も共有されていない場合は、リクエストのタイムアウトを待たずに即座に success: false を返答します。

ページはデーモンのファイルシステムに書き込めないため、JPEG のみを送信します。デーモンはブラウザリースが報告する任意の screenshotPath を無視し、画像自体をネイティブ Host が書き込むのと同じプライベートキャプチャディレクトリ内に、自分で選んだ名前で保存します。ネイティブ Host は引き続き独自の PNG を永続化し、以前と同様にパスを渡します。

mcp_guardrailsはこの条件付きテーブルには含まれません。これは常時有効なタグであり、バイナリが新しい/workspace/mcp予算フィールドをサポートしている場合、オペレーターが予算を設定したかどうかに関係なく常に告知されます。--mcp-client-budgetを設定していないオペレーターも新しいフィールド（budgetMode: 'off'、budgets: []）を取得します。

mcp_guardrail_events（問題 #4175  PR 14b）は、ポーリングループなしでMCP予算状態の閾値超過を検出する型付きSSEプッシュイベントを告知します。2つのフレームタイプがGET /session/:id/eventsに届きます：

• mcp_budget_warning — reservedSlots.size / clientBudgetの上方向75%超過時に一度発火します。比率が37.5%未満（MCP_BUDGET_REARM_FRACTION）に下がった後にのみ再アームされます。PR 10のslow_client_warningヒステリシスを反映していますが、サブスクライバーごとのバックログレベルではなくマネージャーレベルです。ペイロード: { liveCount, reservedCount, budget, thresholdRatio: 0.75, mode: 'warn' | 'enforce' }。warnモードとenforceモードの両方で発火し、offでは決して発火しません。
• mcp_child_refused_batch — 1つ以上のサーバーが拒否された場合、各discoverAllMcpTools*パスの終了時に発火し、さらにreadResource遅延スパーン拒否パスでは長さ1のバッチとして発火します。ペイロード: { refusedServers: [{ name, transport, reason: 'budget_exhausted' }, ...], budget, liveCount, reservedCount, mode: 'enforce' }。modeはリテラル'enforce'です。なぜならwarnモードでは決して拒否しないからです。

両方のイベントはセッションごとのSSE再生リング内に存在します（idを保持するため）、Last-Event-IDを使用して再接続するクライアントはそれらを通じて再開できます。GET /workspace/mcpのスナップショットは、長時間切断後の状態の信頼できる情報源のままです。告知されると常時有効になります — 条件付きトグルはありません。SDKリデューサー状態（DaemonSessionViewState）は、単純な遅延スタイルUIを望むアダプター向けにmcpBudgetWarningCount、lastMcpBudgetWarning、mcpChildRefusedBatchCount、lastMcpChildRefusedBatchを公開します。

ルート

クライアントはsession_turn_statusを機能検出し、GET /session/:id/turns/currentまたはGET /session/:id/turns/:promptIdをポーリングできます。これらのルートはライブ所有Sessionを必要とし、他のワークスペースを読み込んだりスキャンしたりすることはありません。確定結果は、アクティブブランチから境界付きスキャンで読み取られるベストエフォートのトランスクリプトレコードです。prompt_not_foundは、ライブキュー、64エントリのターミナルオーバーレイ、または境界付きアクティブウィンドウ内で結果が見つからなかったことを意味します。resultTextは、最後のツール境界後、オプションのメッセージ書き換え前の生の最終親モデル回答であり、存在しない場合があります。32,768 UTF-16コードユニットを超える結果にはresultTruncated: trueとresultCode: "RESULT_TEXT_TRUNCATED"が含まれます。

GET /health

生存性プローブ。デフォルト形式は、リスナーが生きている場合に200 {"status":"ok"}を返します — 安価で、ブリッジアクセスがなく、高頻度のk8s/Compose生存性プローブに適しています。

すべての管理対象ワークスペースランタイムにわたってブリッジカウンターを集約するデーモン全体のプローブを行うには、?deep=1（?deep=trueまたは裸の?deepも受け入れます）を渡します。まだドレイン中のワークスペースも含みます（情報提供のみであり、真の生存性チェックではありません）：

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

sessions、pendingPermissions、およびactivePromptsは合計です。activeWorkは、任意のランタイムに承認済みだが未確定のプロンプト（FIFO待ちプロンプトを含む）、実行中のバックグラウンドAgent、キュー投入中/進行中のAgentターミナル通知、Session管理下のバックグラウンドシェルまたはワークフロー作業、または子所有のSessionターンがある場合にtrueになります。集約されたsessionホールドは、目標およびcron処理、履歴変更、およびキュー投入中または実行中のMonitor継続を含みます。フォアグラウンドプロンプトはデーモン所有のままです。実行中のMonitor、フォローアップ提案、およびシェルレジストリが追跡できなくなった外部プロセスは、このフィールドの外に残ります。これはセッションスコープです：まだセッションが添付されていないチャネルレベルの作業 — 進行中のスパーン、保留中のリストア、MCPディスカバリまたは認証 — はカウントされないため、activeWorkはデーモンがそのチャネルの回収を依然として拒否している間にfalseを読む可能性があります。このフィールドを「デーモンは回収可能である」と解釈しないでください。セッション所有の作業のみを記述します。activeWorkReportingは、そのブール値のうち実際に保証されている割合を示します：fullは、すべての必須カテゴリを報告する子からの最新レポートによってすべてのライブセッションがカバーされている場合、noneは、セッションがレポートをネゴシエートしていない場合、partialはその間のすべて — 古いスナップショットや必須カテゴリを省略するネゴシエートされた子を含む — です。3つのレポート間隔より古いスナップショットはカバーとしてカウントされなくなります：セッションがアイドルであることを示すレポートではないため、セッションはあたかも子が一度もレポートしなかったかのように、再び保持中として読まれます。ネゴシエートされたが不完全な子に対して通常の自動クリーンアップも無効になります；shellまたはsessionを理解しない子は、完全な現在の述語に従って条件付きクローズを安全に認可できません。完全にサポートされていない過去の子はレガシークリーンアップ動作を保持し、明示的なクローズ、キル、シャットダウン、およびチャネル終了は強制操作のまま残ります。activeWorkStaleMsは、カバーされたセッションの中でブール値が依存する最も古いスナップショットのエージングであり、セッションがカバーされていない場合は0です。これは診断用です。なぜなら鮮度はすでにデーモンによってactiveWorkReportingに格付けされているからです（各チャネルのネゴシエートされた周期を知っているのはデーモンだけです）。格付けは、ランタイムごとに行われて結合されるのではなく、すべての管理対象ランタイムに対して一度計算されます — セッションがないランタイムは空虚に完了しており、それを証拠として扱うと、空のワークスペースが別のワークスペースの未報告セッションを保証できてしまいます。lastActivityAtは最新の非nullワークスペースアクティビティ時刻であり、idleSinceMsはその同じスナップショットから導出されます。channelAliveは、少なくとも1つの管理対象ワークスペースチャネルがライブであることを意味します。すべてのワークスペースが健全であることを意味するわけではありません。connectedClientsとオプションのrateLimitHitsは、ワークスペースごとの合計ではなく、デーモン全体のカウンターのままです。

再起動コントローラーは、以下の場合にデーモンをビジーとして扱うべきです：

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

第3項を削除すると、activeWork === falseは「何の子からも何も知らされなかった」と区別できなくなり、これは行動を取ることが安全でない唯一のケースです。不明な応答と失敗したプローブも再起動を防ぐ必要があります。activePromptsは独立した互換性信号のまま残ります。

これらのフィールドは観測キャッシュであり、再起動リースではありません：新鮮で完全に格付けされた空の回答であっても、サンプリングされた瞬間を記述するものであり、直後に作業が始まる可能性があります。上記のルールは誤った再起動のリスクを大幅に低減しますが、排除するものではありません — 厳密な安全性には、新しい作業のアドミッションを停止し、ドレインを確認し、その後初めてシャットダウンするprepare-restartフェンスが必要です。

⚠️ 深いプローブは情報提供のみであり、実際のライブネス検証やアトミックなリクレームリースではありません。ネゴシエートされた ACP サブプロセスは、ネゴシエートされた頻度でチャネル全体のアクティブワークスナップショットを公開し、デーモンはその鮮度を activeWorkReporting に分類しますが、レポートが欠落しているというだけでチャネルを強制終了することはありません。なぜなら、あるセッションの沈黙はプロセスが死んだ証拠ではないからです。トランスポートのライブネスと停滞した Agent の検出は別個のメカニズムです。connectedClients は REST SSE 接続をカウントし、すべての ACP トランスポートをカウントするわけではありません。アイドル時のリクレームには繰り返しサンプルとグレースフルシャットダウンを使用し、トランスポートおよびワークスペースごとの診断には認証付きの /daemon/status を使用してください。管理対象ランタイムゲッターが例外をスローした場合、深いヘルスは部分的な合計値を返すのではなく 503 {"status":"degraded","reason":"aggregation_failed"} でフェイルクローズし、デーモンログに失敗したワークスペースランタイムが特定されます。ブートストラップ中、ランタイムレジストリの準備ができる前は、Retry-After: 1 を伴う 503 {"status":"degraded","reason":"bootstrap"} を返します。リスナーのライブネスを確認するには、?deep なしのデフォルトの /health を使用してください。

認証: ループバック以外のバインド時、およびループバックが --require-auth で強化されている場合に必須です。通常のループバックバインド（127.0.0.0/8、localhost、::1、[::1]）では、k8s/Compose ポッド内のプローブがトークンを保持する必要がないように、ベアラミドルウェアの前に /health が登録されます。ループバック以外（--hostname 0.0.0.0 など）または強化されたループバックの場合、ルートはベアラミドルウェアの後に登録され、有効なトークンなしでは 401 を返します。これは、未認証の呼び出し元が任意のアドレスをプローブして qwen serve の存在を確認できる可能性があり、ポートスキャンと組み合わさると悪影響のある低深刻度の情報漏洩となるためです。通常のループバック免除においても、CORS 拒否 + Host アドレスリスト制限は適用されます。

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

これらの認証済みルートは、選択されたワークスペースとは独立して、デーモンの Qwen Code インストールを管理します。ACP セッション トランスポートを使用する SDK クライアントからのリクエストも含め、常に REST を使用します。daemon_update 機能はプロトコルを通知し、可用性は返される状態によって決定されます。

GET はダウンロードやアクティベーションを行わずにリリースを確認します。成功した確認は 15 分間、エラーは 1 分間キャッシュされ、?refresh=true は新しい確認を要求します。同時の確認は 1 つのルックアップを共有します。レスポンスには state (available、up-to-date、installing、ready、restarting、unavailable、または error)、canInstall、オプションの currentVersion と latestVersion、およびオプションの instructions と message が含まれます。currentVersion は、更新が準備された後を含め、実行中のデーモンを識別します。サポートされていないインストール方法は、available を canInstall: false および手動手順とともに報告する場合があります。

自動更新には、POSIX process.execve を備えた実際の CLI ライフサイクル、スタンドアロン インストール、または公開されたランチャーを実行しているグローバルな npm/pnpm/yarn/bun インストール（ステージングはグローバル プレフィックスに書き込まないため、root 所有の npm プレフィックスが含まれます）、および general.enableAutoUpdate を許可するオペレーター設定が必要です。埋め込みサーバー、Windows、サポートされていない Node ランタイム、開発モードは unavailable を報告します。グローバル/システム設定のみが適用され、ワークスペース設定ではインストールを有効にできません。接続はプライマリ リスナーとそのデーモン ランタイム トークン、またはトークンなしで明示的に信頼されたループバック デプロイメントを使用する必要があります。ペアリングされたブラウザと Local Control 接続は、資格情報またはリスナーが再起動後も存続しないため、unavailable を報告します。それらの更新ミューテーションは 403 update_connection_unsupported を返します。

両方の POST ルートは、厳格なミューテーション ゲートのデーモン オペレーター権限を必要とし、パラメーターを受け入れません。サーバーがリリース、宛先、ランチャーを選択します。クライアントはバージョンやコマンドを指定できません。

• POST /daemon/update/prepare はバックグラウンド ダウンロードを開始し、state: "installing" を伴う 202 を返します。アクティブなインストールは変更しません。状態が ready になるまで GET をポーリングしてください。繰り返しの準備は同じ操作を共有し、準備済みの更新は 200 を返します。利用可能な自動更新がない場合は 409 update_unavailable を返します。
• POST /daemon/update/restart は準備済みの更新を必要とし、そうでない場合は 409 update_not_ready を返します。更新をアクティベーションする前に、202 と state: "restarting" で応答し、デーモンをグレースフルにシャットダウンし、プロセスを更新後のランチャーに置き換えます。繰り返しのクリックは 1 つの再起動を共有します。応答後、デーモンは現在のリリースを一度再解決します。それが準備済みのものより新しく、ワンクリックでカバーできる場合、新しいリリースがステージングされ、準備済みのペイロードは破棄されるため、長期稼働中のデーモンは最初に準備した時点での最新ではなく、現在の最新に到達します。新しいペイロードは、置き換えられたものが破棄される前にコミットされ、その破棄はベストエフォートです。失敗した破棄はディスクをリークしますが、新しいペイロードが孤立したり、半分削除されている可能性のあるものにフォールバックしたりすることはありません。その後、latestVersion は新しいターゲットを報告し、state は restarting のままになります。再解決またはステージングの失敗は代わりに準備済みのリリースを適用します。レジストリの障害により、クリックが実行中のバージョンに取り残されることはありません。置き換えは PID、作業ディレクトリ、CLI オプション、バインドされたポート、有効なデーモン トークンを保持し、古いバージョン ピンをクリアし、ブラウザを開き直しません。クライアントは currentVersion が変化するまで GET をポーリングし、更新が要求されたときにキャプチャされた URL でドキュメントをリロードします。ステージングは 202 の後に実行され、数分かかる可能性があるため、クライアントはクリックからではなく、継続的な到達不能性から再起動期限を測定します。応答を返し続けているデーモンはまだ動作しています。寛大な絶対上限（20 分）は、到達可能だが決して restarting を離れないデーモンに対してバックストップとして機能します。これは単一のタイムアウト定数の上ではなく、ステージング チェーン全体の上に位置します。スタンドアロン アーカイブのダウンロードは OSS と GitHub を順次試み、それぞれに 5 分の予算があり、チェックサムと署名の取得にはさらに最大 2 分かかり、1 回の再ステージングではアクティベーション前にダウンロードと検証に約 12 分費やす可能性があります。管理された npm 子プロセスは 10 分に制限されています。すべてのギブアップ パスは画面に再試行可能なエントリを残します。スタックしたデーモンは制御が表示しない restarting を報告し続けるためです。再起動が承認されると、プロセスが置き換わるまで restarting はスティッキーになります。したがって、currentVersion が変更されないまま他の状態を報告する到達可能なデーモンは、置き換えが新しいビルドに反映されなかったことを意味します。クライアントは待機を終了し、確定した状態を発行し、バージョン変更を永久に待つ代わりに失敗を報告します。このチェックは、承認後に 開始 されたポーリングにのみ適用されます。ステータス要求と再起動要求は独立しているため、以前に開始されたポーリングが再起動前のスナップショットを後に配信することがあり、それを確定したデーモンとして読み取ると、誤った失敗を報告し、成功した更新がユーザーに負っているリロードを抑制してしまいます。スタンドアロン ランチャーの検証はサービスを閉じる前に実行されます。チェックが失敗すると、デーモンは実行されたままになります。シャットダウン開始後またはプロセス置換中の障害は、回復が保証されません。

Web Shell はサポートされている利用可能な更新をバックグラウンドで自動的にチェックし準備します。準備済みの更新が完了した際、または手動手順を含む更新が利用可能になった際に、バージョンの横にある更新ボタンを表示します。手動手順の状態では、ボタンをクリックするとチェック時の手順を含むポップオーバーが開き、準備や再起動は行われません。準備と可用性はワークスペースランタイムのリロード後も維持されます。準備済みの更新はターゲットを固定します。?refresh=true を含むポーリング GET は、準備済み latestVersion を報告し続け、再ダウンロードを行わないため、複数のリリースにわたって稼働し続けるデーモンがバックグラウンドでダウンロードを繰り返すことはありません。ターゲットの再解決が行われるのは再起動時のみです。通常のデーモンシャットダウンでは準備済みダウンロードが破棄されます。有効化失敗時はデーモンの稼働を継続し error を報告します。1 分間のエラーキャッシュ経過後の次回チェック時に、リトライ用の新しいダウンロードを準備できます。自動更新を無効にすると、可用性が削除され、再起動開始前にダウンロードがクリーンアップされます。一度再起動が進行中になると中断されません。状態が restarting の間、ステータス、prepare、restart ルートはすべてオペレーター設定を参照せずに応答し、シャットダウン時のクリーンアップは no-op となるため、数分かかる再ステージング中にペイロードが取り除かれることはありません。ready 状態でボタンをクリックすると、デーモン全体が明示的に再起動され、アクティブなセッションが中断されます。

GET /daemon/status

読み取り専用のオペレーター診断機能。/health と異なり、これは通常のデーモン API です。ループバックバインドを含め、ベアラ認証およびレート制限の後に登録されます。クエリパラメータ:

• detail=summary （デフォルト）はメモリ内のデーモン状態のみを読み取ります。
• detail=full には、ライブセッション診断、ACP 接続診断、認証デバイスフローカウント、およびワークスペースステータスセクションも含まれます。
• その他の detail は 400 { "code": "invalid_detail" } を返します。

summary は意図的にワークスペースステータスメソッドを照会せず、ACP チャイルドプロセスを開始せず、セッションを生成しません。full は各ワークスペースセクションを独立して照会します。タイムアウトまたは例外が発生した場合、そのセクションのみが unavailable とマークされ、workspace_status_unavailable 問題が追加されます。

レスポンス形式：

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

マルチワークスペースレスポンスには、{ id, cwd, displayName?, primary, trusted } を持つトップレベルの workspaces[] 行も含まれます。任意の表示名が未設定の場合は省略され、プレゼンテーション専用として扱われます。ステータスコンシューマーはランタイムを相関付けるために id または cwd を使用し続ける必要があります。

runtime.perf はオプションです。存在する場合、デーモンプロセスのイベントループ遅延、プロンプト FIFO キュー待機サンプル、およびデーモンチャイルドパイプバイトカウンターのみを報告します。ACP チャイルドプロセスのイベントループ遅延は /daemon/status に含まれません。

status は、いずれかの問題にエラー重大度がある場合は error、警告重大度がある場合は warning、それ以外の場合は ok です。問題コードは安定しており、session_capacity_high、connection_capacity_high、pending_permissions、acp_channel_down、preflight_error、mcp_budget_warning、mcp_budget_exhausted、rate_limit_hits、channel_worker_exited、channel_worker_partial_connect、channel_restore_failed、および workspace_status_unavailable が含まれます。リスナーが準備できてから完全なランタイムがマウントされるまでの短い期間中、/daemon/status は daemon_runtime_starting を報告する場合があります。非同期ランタイムマウントが失敗した場合、非ステータスランティアルートが 503 を返している間に daemon_runtime_failed を報告します。

runtime.activity はデーモン全体のプロンプトアクティビティを報告します。activePrompts は進行中のプロンプトを持つセッション数をカウントします。pendingPrompts は実行中のプロンプトと FIFO 待機中のプロンプトを含め、まだ完了していないすべての受け入れられたプロンプトをカウントします。queuedPrompts は受け入れられたがディスパッチされていない FIFO 待機中のプロンプトをカウントします。lastActivityAt は最後のプロンプト開始/終了またはセッション生成の ISO 8601 タイムスタンプです。null は、デーモンが起動以来一度もアクティビティを処理していない場合に表示されます。idleSinceMs は応答生成時に lastActivityAt から計算されます。

limits.memory は加算的であり、デーモンの解決済みメモリ数値を報告します：必須の enforced: false、childHeap オブジェクト（mode: off、observe、または admit；admissionEnforced は管理された admit の場合にのみ true）、maxConcurrentChildren および perChildCeilingMb（どちらも mode: 'off' 下での null で、これは何もモデル化しません）、そして perChildCeilingMb はさらに、modeled.minChildHeapMb 内でパーティションをモデル化できない場所 wherever null を報告します — つまり、プールがその階層で子プロセスを1つでもカバーできないか、上限が modeled.legacyChildCeilingMb にキャップされると天井がその下に着地するためです。これは floor(available / 2) であり、1024 MB 未満のホストでは床の下に落ちます。これは決して 0 にならず、そのような場合 maxConcurrentChildren は 0 です。パーティションをモデル化しないホストは欠落したモデルではなく計算された回答であるためです。また refusals（モデル化された制限を超えていたであろうスポーン）、configuredBudgetMb、effectiveBudgetMb（解決済みの cgroup/ホストメモリでキャップされた設定値）、budgetSource（flag / derived）、availableMemoryMb、availableMemorySource（constrained / host）、insufficientMemory、および rootReserveMb、childPoolMb、minChildHeapMb、maxChildHeapMb、legacyChildCeilingMb（ACP 子が今日受け取る天井の保守的なモデルで、実際の数値より低くなる可能性があります）を保持する modeled オブジェクトを含みます。runtime.memory はさらに registeredWorkspaces（登録数 — ドレイン中、移行中、またはブロックされているものを含む、削除されていないワークスペースエントリ。ライブ子プロセス数ではありません）、activeAcpChildren（ライブで終了していないチャネルを持つデーモン管理の ACP 子プロセス — 移行中またはブロックされているエントリを含みますが、キルが開始されたワークスペースは子が終了していなくても除外されます。チャネルワーカー、MCP 子孫、または未接続のスポーン予約は含まれません）、childRssCoverage（active_children — ライブチャネルを持つすべての ACP 子プロセス。これは activeAcpChildren がカウントするセットです。古いデーモンは primary_only を送信します）、以下で説明される children オブジェクト、および recommendedShareAtRegisteredMb（ワークスペースが登録されていない場合は null）と recommendedShareAtActiveMb（アクティブな子プロセスがない場合は null）を保持する modeled オブジェクトを含みます。各シェアはレガシー子プロセス上限でキャップされ、天井が許可する場合のみ最小子プロセスヒープでフロアされます。小さなホストでは天井が床の下にあるため、シェア × カウントが子プロセスプールを超える可能性があります。シェアはプールのパーティションではなく参考情報として解釈してください。子プロセスヒープのサイジングも参考情報です。これらの値から派生する子プロセススポーン引数はありません。オプトインの admit はモデル化された同時子プロセス数を強制しますが、デフォルトの observe は拒否されたであろう事象を記録するだけです。runtime.memory.committedAcpChildren はレジストリ解放まで終了中の子プロセスを含む、管理された ACP 予約と接続された子プロセスをカウントします。管理されたレジストリが利用できない場合は null です。childHeap は modeled.childPoolMb の固定パーティションをモデル化します。すべての子プロセスが同じ perChildCeilingMb を受け取るため、モデル化された合計はスポーンごとのシェアとして蓄積するのではなくプール内に収まります。refusals はアドミッションプレッシャーとしてのみ解釈してください。カウントが 0 でも、パーティションを適用しても安全であるとは 限りません。子プロセスははるかに大きなホスト由来の天井で実行されるため、perChildCeilingMb より多くの旧世代スペースを必要とするワークロードはここでは健全であり、パーティションが適用されて初めて失敗するからです。非ゼロのカウントが容量プレッシャーを意味しない理由がさらに2つあります。アドミッション決定は終了する子プロセスが終了するまでカウントするため、すでに maxConcurrentChildren に達しているデーモンでは、すべてのチャネル置換が重複ウィンドウ中に拒否を予約します。また、パーティションをモデル化できないほど小さいホストでは maxConcurrentChildren は 0 であるため、refusals は総 ACP スポーン数と等しくなり、insufficientMemory がそれを説明するフィールドとなります。admit では、ゼロスロットモデルは起動に失敗します。容量枯渇に直面した完全管理デーモンは、ライブセッションや保留中の作業がない最も使用頻度の低い空の ACP を1つ回収し、追跡された解放を待ってから、スポーン前に一度だけアドミッションを再試行します。ロードされたセッションは保護され、ワークスペース登録と保存された履歴は保持されます。refusals カウンターは、最初の拒否後に成功した回収を含む、拒否されたアドミッション試行をカウントします。最終的なユーザー可視の失敗ではありません。枯渇した容量は、Retry-After なしで、code: "acp_child_capacity_exhausted"、maxConcurrentChildren、および committedAcpChildren（拒否された予約を除く）とともに REST HTTP 503 を返します。ACP JSON-RPC は、そのコードを含む data.errorKind、data.httpStatus: 503、および同じカウンターを持つ -32603 を使用します。検証済みのプリディスパッチスタンドアロン作成ロールバックは standalone_creation_rolled_back、そのセッション ID と再試行可能性を保持し、容量コードとカウンターを capacity の下にネストします。不確実な作成結果は既存のリカバリセマンティクスを保持します。クライアントは自動容量再試行を停止し、ドラフトまたは選択されたセッションを手動再試行のために保持すべきです。通常の runQwenServe パスでは、ブートストラップアプリが作成される前に予算が解決されるため、limits.memory はブートストラップウィンドウ中すでに設定されています。runQwenServeImpl をバイパスする直接埋め込みなど、予算を解決しないパスでのみ null です。SDK タイプは null を許可するため、正しいクライアントはこれに対応します。

runtime.memory.children はそのブロック内で加算的であり、childRssCoverage が名前を挙げる子プロセス全体の集約 RSS を報告します：rssBytes（それらの自己申告 RSS の合計）、sampled（測定値を提供した数）、oldestReadingAgeMs（合計内の最古の測定値の経過時間。これにより呼び出し側は部分間の時間差を知ることができます）。sampled の分母は兄弟要素の activeAcpChildren であり、ブロック内には繰り返されません。sampled が低い場合、rssBytes は合計ではなくフロアです。サンプリングはアクティブな SSE/WS ウォッチャーによってゲートされるため、誰もストリーミングしていないデーモンに対するステータス要求は、ライブの子プロセスがあっても sampled: 0 を報告します。隣接する activeAcpChildren によりこのギャップが見えるようになり、rssBytes: 0 と sampled: 0 は決して測定ゼロを意味しません。oldestReadingAgeMs は何もサンプリングされなかった場合、およびすべての寄与者がこのフィールド以前からのブリッジである場合にも null となるため、「新鮮」を意味することはありません。合計は過大評価かつ過小評価として読んでください：プロセスごとの RSS を合計すると子プロセス間で共有されるページが二重にカウントされる一方、各子プロセスは自身のプロセスのみを報告するため、その MCP 子孫とすべてのチャネルワーカーが欠落しています。これはデーモンツリーのメモリではありません。primary_only を報告するデーモンはこのフィールドを送信しないため、SDK ミラーではこのフィールドはオプションです。

runtime.memory.children.heap はそのブロック内で加算的であり、各 ACP 子プロセスの V8 オールドジェネレーションのライフタイム・ハイウォーターマークを報告します。これは 合計ではなく最大値として集約されます: peakOldGenerationBytes, peakLiveSetBytes, peakTotalHeapBytes, majorGcCount, majorGcMs, unclassifiedSpaceNames, および reported。ヒープ上限は子プロセスごとに適用され、ピークに達したタイミングが異なるため、合計値には意味がありません。各フィールドは報告された子プロセス間での独立した最大値であり、特定の子プロセスのプロファイルではありません。また、子プロセスごとの上限はそれぞれの軸に対して個別に判定されます。reported は sampled のうちいくつが寄与したかをカウントし、一部の子プロセスがこれらのフィールドより前に存在していた場合は値が低くなります。すべてのバイト数は オールドジェネレーション をカバーしています。これは --max-old-space-size が実際に制限する対象であり、old_space だけではありません。なぜなら、子プロセスは old_space が数メガバイトしかない状態で上限を使い果たすことがあり、large_object_space がすべてを保持している可能性があるからです。peakOldGenerationBytes はコミット済みバイト数で、子プロセスに割り当てられた上限とともに増加するため、ワークロードが必要とする要件というよりも、必要とする量の上限として解釈してください。peakLiveSetBytes はメジャー GC 後も残存するメモリ量で、上限の変動に影響されないため、子プロセスが一つでも収まらないことを示せる指標となります。GC エントリは非同期で到着し、コレクションと読み取りの間で割り当てられたものはすべてカウントされるため、正確なライブセットではなく上限として解釈してください。peakLiveSetBytes はメジャー GC が観測されるまで 0 です。これは測定結果ではなく不在を示しています。unclassifiedSpaceNames は、報告されたどの子プロセスも分類できなかったヒープスペースの和集合です。V8 はバージョン間でスペースの名前を変更したり追加したりするため、未知のスペースは合計から除外されます。除外すると過小評価になるため、配列が空でない場合、バイト数は不完全であり、完全な測定値として解釈してはいけません。サンプリングされた子プロセスが一つも報告しない場合、オブジェクト全体はゼロ化されたオブジェクトではなく null になります。SSE/WS ウォッチャーが接続されていない場合は何もサンプリングされないため、これはエッジケースではなく通常の状態です。これらはすべて観察的なものであり、ここでの子プロセスのサイズ設定、起動拒否、または limits.memory.enforced を false から移動させることはありません。

runtime.memory.pressure はそのブロック内で加算的であり、デーモンルート自身のメモリ圧力を報告します: mode (off / observe), level (normal / soft / hard / critical), source (rss / heap / unknown), ratio, および比率の算出元となる 6 つの生数値 — rssBytes, rssRatio, availableBytes, heapUsedBytes, heapRatio, heapLimitBytes。ratio は rssRatio と heapRatio の大きい方であり、source はどちらであったかを名前で示します。同値の場合は rss として報告されます。availableBytes はバイト単位の limits.memory.availableMemoryMb です。これは意図的に検出された cgroup/ホストの値であり、effectiveBudgetMb ではありません。プロセスを終了させるのは実際の制限であり、オペレーターのポリシー数値ではないためです。source: "unknown" は両方の分母が測定不可能であることを意味し、健全であると解釈してはいけません。level はそのような場合にのみ normal となります。分類すべきものがないためです。これらの数値は デーモンのルートプロセスのみ をカバーしています。これはこのプロセス自身の memoryUsage() であるため、子プロセスが増加しても変動しません。runtime.memory.children はそれらを別々に報告し、どちらの数値もプロセスツリーのメモリではありません。両モードともブロック全体を報告します。ただし、observe のみがパスなしの daemon_memory_pressure 警告をステータスロールアップに追加するため、off はトップレベルの status を変更しません。どちらのモードでも修復処理は行われません。SDK ミラーでは、このフィールドが存在する以前に runtime.memory を出荷したデーモンがこのブロックをフィールドなしで送信するため、このフィールドはオプションです。

limits.maxRegisteredWorkspaces は加算的であり、解決済みのユーザー登録上限（デフォルト 256、1 から 256 で設定可能）を報告します。limits.maxChannelControlWorkspaces は、チャネルが無効になっている場合でも、標準デーモンにおける制御/復旧オーナーの独立した上限 25 を報告します。カスタムコントローラーは、この上限を実施する場合にのみこのフィールドを広告します。これらのフィールドはブートストラップおよび ready レスポンスの両方に存在しますが、古いデーモンでは省略される場合があります。チャネルコントローラーは、候補ワーカーを構築する前に、上限を超える過渡的なオーナー統合を 409 channel_control_workspace_limit_reached で拒否します。起動時の統合が上限を超える場合は、リスナーが公開される前に起動が失敗するため、HTTP インターフェースはありません。登録容量は SDK チャネルタイムアウトを決定しません。

limits.maxTotalSessions は加算的です。null は、有効なデーモン全体の新しいセッション上限が無効であることを意味します。解決済みの登録容量（デフォルト 256、QWEN_SERVE_MAX_WORKSPACES または埋め込み maxRegisteredWorkspaces 経由で設定可能）が 25 を超え、かつ --max-total-sessions が省略されている場合、標準デーモンは一つの起動ワークスペースであっても固定総数 800 を使用します。登録容量が 25 以下の場合、有限の maxSessionsPerWorkspace を持つ複数の起動/復元ワークスペースは、同じ起動プラス復元カウントに対する maxSessionsPerWorkspace * workspaceCount として有効総数を一度だけ導出します。一つの起動または復元ワークスペースは無制限のデフォルトを保持します。明示的な総数制限（無効値を含む）が優先されます。後続の動的登録によって総数は再計算されません。直接の createServeApp 埋め込みは、独自の共有アドミッションポリシーを提供する必要があります。設定されると、デーモン全体で新しいセッション作成を制限し、既存の session_limit_exceeded エラー形状と scope: "total" を用いて総数制限違反を報告します。

runtime.channel.live はデーモン内の ACP ブリッジチャネルを報告します。これはチャネルアダプターワーカーではありません。デーモン管理チャネルは runtime.channelWorker を使用し、その state は disabled、starting、running、exited、failed、または stopped のいずれかです。ワーカーが running に到達して終了した場合、/daemon/status はデーモンをオンラインのままにし、警告問題コード channel_worker_exited を報告します。

明示的な qwen serve --channel ... からのデーモン管理チャネルワーカー起動は fail-fast のままであり、永続化された起動設定より優先されます。フラグなしのブートでは、信頼できるすべての登録済みワークスペースから serve.channels を復元し、それぞれが独自のスコープ設定内のリストを提供します。復元された名前は、通常どおり所有者が解決される単一の選択を形成し、名前をリストしたワークスペースが曖昧な所有権タイブレークを解消します。そのブート帰属はデーモンが稼働している限り持続します。PUT /workspace/channel によるそのような名前の再有効化は、途中で選択が停止されていた場合でも、ブート時と同じ方法で解決します。プライマリ以外のワークスペースが提供した名前は、解決できない場合にログとともに破棄されるため、あるワークスペースの古いエントリーによって他のワークスペースが孤立することはありません。プライマリワークスペースがリストした名前は、他のワークスペースにもリストされているかどうかに関係なく、復元全体を失敗させます。all はプライマリ専用として残ります。他の場所では無視され、報告されます。

ブート後に登録された信頼できるプライマリ以外のワークスペースは、独自の serve.channels も復元し、チャネルランタイムを読み込み、他に何も保持していない場合はチャネルサービスリースを予約します。その復元は:

• デーモン実行ごとに一度だけ発生します — ワークスペースが何かを要求した時点で記録されるため、後での削除と再登録、または信頼の再実体化によって、その間にそれらのチャネルの一つを停止したオペレーターの操作が取り消されることはありません;
• 明示的な --channel 選択下では発生しません。後から登録されたワークスペースによって拡張されることもありません;
• DELETE /workspace/channel がホスティングを停止した後、PUT /workspace/channel が選択を再度コミットするか、デーモンが再起動するまでは発生しません;
• コミット済みの all 選択はそのままにします;
• ワークスペース名をコミット済み選択に追加する際は、一度に変更し、遅延復元は一度ずつ行います。ホストできない名前を破棄して残りを保持するブートとは異なり、属性付けできない名前が存在する場合、そのワークスペースのリスト全体が復元されず、エラーは以下で説明する方法でログに記録され報告されます。

登録はチャネル制御を一切待ちません。復元はチャネル制御レーンにキューイングされ、応答はそれを待たずに書き込まれます。また、デーモンが既にホストしているチャネルに対して登録または信頼変更によってトリガーされる調整も同様に待機しません。したがって、準備完了にならないワーカーは、その後にキューイングされたチャネル処理のみを遅延させ、他の登録や信頼調整を遅延させることはありません。裏を返せば、POST /workspacesからの201はそのワークスペースのチャネルが稼働中であること、または所有する既存ホストチャネルの再起動が完了したことを意味しません。これについてはGET /workspace/channelを参照してください。

明示的な選択、ブート時のserve.channels復元、上記のような登録がない場合、チャネルランタイムの読み込みは遅延のままになります。

保存された起動名は空であってはならず、先頭または末尾の空白を含んではならず、安全でない制御文字や不可視文字を含んではなりません。無効なエントリは個別にスキップされ、配列インデックスとともにログに記録されます。起動時にそれらを他のインスタンス名へトリミングしたり、設定を書き換えたりすることはありません。ワーカー引数は--channel=<value>を使用し、先頭のダッシュを名前の一部として保持します。

ワーカー起動前に無効な起動フィールド、検証エラー、またはリースエラーが発生した場合、自動復元はスキップされ、serve.channelsを特定するログが残ります。一方、無関係な設定は有効なままです。ワーカー起動が失敗しても、クリーンアップが成功すればデーモンの継続実行が許可されます。グローバルランタイム起動タイムアウトと未確認のワーカー停止は、既存の起動失敗パスに従い、ワーカー終了が未確認の間はリースが保持されます。チャネル管理は永続化された起動設定と実際のランタイム状態を報告します。

一部のserve.channels名でデーモンが起動しなかったものは、ログだけでなく報告されます。そのような名前はコミット済み選択に参加しないため、ワッカースナップショットには含まれません。報告されるケースは次の3つです：

• 設定された起動選択のうち、ワーカー起動に失敗したもの。これはチャネルなしでデーモンがサービスを提供し続けるブートパスにおいて発生します。
• ワークスペースへの属性付け中にブート所有権レゾルバが破棄した名前。これをリストしていたすべてのワークスペースに対して報告されます。
• 各チャネルとそのエラーを名指しします。これが完全な表面であり、ブートレコードが書き込まれている間存在する唯一の

ブートストラップレスポンスにも含まれます。ワークスペースごとに最大64個のチャネルが名指しされ、

• /daemon/statusはワークスペースごとにchannel_restore_failed警告を一つ報告し、各チャネルとそのエラーを記載します。これは完全な情報であり、ブートレコードが書き込まれている間に存在する唯一の要素であるブートストラップ応答にも含まれます。ワークスペースあたり最大64チャネルまで記載可能で、各名前は128文字に制限され、リストが長い場合はand <n> moreが付与されます。
• そのワークスペースのGET /workspaces/:workspace/channelsは、stoppedではなくruntime: { state: "error", lastError }を用いてチャネルを一覧表示します。ここでlastErrorは、ワーカーがそのチャネルについてエラーを報告した場合はアダプター自身の起動エラーであり、そうでない場合は試行のエラーです。この情報はワークスペース固有のチャネル設定スコープから構築されるため、そのスコープで定義されている名前のみを保持できます。登録済みワークスペースが設定していない名前や、設定が別のワークスペースにある名前はここに行を持たず、/daemon/statusでのみ報告されます。

serve.channels名がホストされないままになるその他の事象は、デーモンログでのみ診断されます。リスト全体が読み取れないか無効だったために失われた名前、プライマリがallを選択したために非プライマリワークスペースのリストが破棄された場合、コミット済み選択がallであるために遅延復元がスキップされた場合、およびリモート（SSH）ワークスペースのリストです。これらについてはデーモンログを確認してください。

レポートは、チャネルがホストされている間（このワークスペースまたは別のワークスペースからの復元による）、ワークスペースの登録が解除されるまで、またはオペレーターが操作を行うまで保持されます。その操作とは、チャネルに対する POST の開始、停止、再起動、PUT/DELETE /workspace/channels/:name、または選択内容を変更する PUT/DELETE /workspace/channel です。PUT /workspace/channels/:name/startup はレポートをクリアしません。失敗した試行について言及せずに serve.channels を書き換えるだけです。レポートはメモリに保持されます。再起動されたデーモンは再度復元を行い、その試行の結果を報告します。エラーテキストは認証情報を削除し、デーモンログのレンダリング方法と同様に長さが制限されています。

ワーカーが準備完了状態に達した後、予期しない終了はサーブスーパーバイザーにより制限付きポリシー内で再起動されます。5分間のウィンドウ内で最大3回の再起動試行が行われ、バックオフ時間は1秒、5秒、15秒の順です。ワーカーは15秒ごとにIPCハートビートを送信します。45秒間ハートビートが観測されない場合、スーパーバイザーはワーカーをスタールとみなし、強制終了してstaleHeartbeatAtを記録し、同じ再起動パスを使用します。

runtime.channelWorker には、追加の運用フィールドが含まれる場合があります: requestedChannels, pid, startedAt, exitCode, signal, error, restartCount, lastExitAt, lastRestartAt, nextRestartAt, lastHeartbeatAt, staleHeartbeatAt, startupFailures, および startupFailuresTruncated。各起動失敗には channel, phase (現在 connect), オプションのアダプター提供の code, および認証情報をマスキングした message が含まれます。現在のワーカー世代に対しては最大 64 件の失敗が保持されます。切り詰めフラグは、さらに多くの失敗が観測されたことを意味します。code は診断用であり、安定したクロスアダプター分類ではありません。restartCount は、この serve プロセスが行った再起動試行の累計回数です。restartCount > 0 を持つ実行中のワーカーは、他の問題がない限り健全です。requestedChannels に channels から欠落している名前が含まれる実行中のワーカーは、channel_worker_partial_connect を報告します。

マルチワークスペースデーモン (--workspace の繰り返し) では、runtime に加えて channelWorkers[] が含まれます。これは所有するワークスペースごとのエントリで、それぞれが workspaceId, workspaceCwd, および primary で注釈付けされた channelWorker スナップショットです。互換性のため、channelWorker はプライマリワークスペースのスナップショットとして引き続き設定されます。単一ワークスペースデーモンでは channelWorkers[] は省略されます。

デーモン管理のチャネル制御

channel_control 機能は、ランタイム選択リソースを通知します。互換性パスが単数形の /workspace プレフィックスを使用する場合でも、このリソースはデーモン全体に適用されます。ランタイム選択は永続化されず、デーモンの起動時オプション --channel を変更しません。

GET /workspace/channel はイミュータブルなマネージャースナップショットを返します:

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

無効な場合、selection は null です。pendingSelection は変更要件中のみ存在します。transition は idle, starting, reconciling, stopping, または rolling_back のいずれかです。

PUT /workspace/channel は strict-gated であり、正確に1つの選択を受け入れます:

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

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

名前はトリムおよび重複排除されますが、ソートは行われません。空の名前配列は無効です。all はプライマリワークスペース専用です。無効から有効への変更は 201 を返します。冪等な PUT または置換は 200 を返します。レスポンスは { changed, replaced, partial, state } です。同じ選択の場合、健全なワーカーはその場に留まりますが、ワーカーが停止または失敗した同じ選択の場合は回復します。

DELETE /workspace/channel は厳格ゲート付きで冪等です。{ changed, state } を返します。成功時の状態は無効です。POST /workspace/channel/reload も厳格ゲート付きであり、設定を再読み込みし、ワークスペースグループを再解決し、コミット済みの選択を強制的に調整します。無効な場合は 409 channel_worker_not_enabled を返します。channel_reload 機能は、マネージャーがコミット済みで再読み込み可能な選択を持っている場合にのみ動的に通知されます。

すべての有効化、置換、再読み込み、停止、およびデーモンシャットダウンは、1 つの FIFO ライフサイクルレーンに入ります。GET はそのレーンを待ちません。順序付けられた選択が変更されていないワークスペースグループはオンラインのままです。置換失敗時は、新たに開始されたワーカーの停止と、以前のコミット済み選択の復元を試みます。クリーンアップや復元も失敗する可能性があるため、クライアントは rolledBack, rollbackError, および state を確認する必要があります。デーモンはトランザクション全体を通じてチャネルサービス PID リースを保持し、関連するすべての子プロセスの終了が確認されるまで解放しません。

安定した制御エラーは次のとおりです:

• 400 invalid_channel_selection、channel_workspace_mismatch、または ambiguous_channel_workspace
• 403 untrusted_workspace
• 409 channel_service_conflict、channel_worker_not_enabled、または channel_control_workspace_limit_reached
• 500 channel_worker_stop_failed
• 502 channel_worker_start_failed で、rolledBack とオプションの資格情報マスキング済み rollbackError を伴います
• 503 daemon_draining

信頼できるループバック権限なしでゲートに到達したトークンなしのプライマリリクエストからの厳格な書き込みは、制御コードの実行前に 401 token_required を返します。設定された認証情報の欠落または無効、およびペアリングされていない Local Control 認証情報は、より早い段階で通常の 401 Unauthorized で拒否されます。信頼できるループバックのプライマリリクエストは通常どおり実行されます。リクエストが開始されると、HTTP クライアントの切断によってライフサイクルトランザクションはキャンセルされません。クライアントは同じ PUT を安全に再試行できます。

502 channel_worker_start_failed の場合、レスポンスには startupFailures[] と startupFailuresTruncated も含まれる場合があります。各失敗により、試行されたワーカーの信頼できる workspaceCwd が追加されます。これらのフィールドは失敗したトランザクションを記述しますが、state はロールバック後の現在の状態を記述します。後続の GET では失敗した試行は保持されません。部分的に接続されたワーカーは代わりに成功を返し、その失敗をワーカーのスナップショットで公開します。接続されたアダプターのない明示的な --channel ブートは起動に失敗します。設定由来の起動失敗はログに記録され、グローバルランタイム起動タイムアウトの対象となりますが、クリーンアップが成功すればデーモンの継続を許可します。クリーンアップの確認に失敗した場合、通常の起動失敗動作とサービスリースが保持されます。

--daemon-url なしの qwen channel status は pidfile メタデータを読み取り続けます。--daemon-url がある場合は GET /workspace/channel を読み取ります。再起動ウィンドウ中、serve が所有する pidfile は予約されたままですが、workerPid は省略されるため、クライアントは古いワーカープロセスを表示しません。マルチワークスペースデーモンでは、pidfile には追加の workers[] 配列 (ワークスペースごとの workspaceId / workspaceCwd / channels / ライブ workerPid) も含まれますが、上位レベルの channels (和集合) と workerPid (プライマリ) は古いリーダー向けに設定されたままです。単一ワークスペースデーモンは元の単一ワーカー形状を維持します。ワーカーの stdout/stderr は、ベアラートークン、機密性の高いワーカー環境値、およびプロキシ URL 認証情報をマスキングして、デーモンログに転送されます。

ワークスペースチャネル管理

channel_management 機能は、ワークスペーススコープの Channel 設定とランタイム管理を通知します。単数形の /workspace ルートはプライマリランタイムを対象とします。/workspaces/:workspace は、登録済みで信頼できる正確なランタイムを解決し、プライマリランタイムへのフォールバックは行いません。

読み取り専用のディスカバリーでは次を使用する：

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

GET .../channels/events は、解決されたワークスペースのチャネルイベントジャーナルを { "events": [...], "truncated": boolean } として Cache-Control: no-store と共に返し、オプションの channelLinkMeta メンバー（チャネルインスタンス名から非シークレットリンクメタデータへのマップ：type および baseUrl。それぞれが文字列として設定されている場合にのみ存在し、GitHub チャネルの場合は解決された webOrigin を含む。Web UI のオリジンクライアントは API ルートから再導出するのではなく、これを直接連結すべきです）を含みます。メタデータは、チャネルワーカーが実行するマージされたシステム＋ユーザー＋ワークスペース設定から解決されます。スコープローカルの管理リストには、別のスコープで設定されたチャネルは含まれません。また、解決された cwd がクエリ対象のワークスペースに属するチャネルにフィルタリングされるため、あるワークスペースが別のワークスペースのチャネルメタデータを受け取ることはありません。これにより、クライアントはユーザーまたはシステム設定から継承されたチャネルであっても、ジャーナル行（例：GitHub PR または issue 参照）にリンクできます。このメンバーは、解決されるチャネルがない場合は完全に省略され、古いデーモンはこれを送信しません。設定読み取りエラーが発生した場合、ジャーナル読み取りが失敗するのではなく、このメンバーが存在しない状態へと劣化します。各イベントは、チャネルが実行した操作（受信メッセージの受理またはスキップ（機械的理由：reason_filter、mention_required、duplicate、送信者ゲートによる拒否、github_api_error）、処理に失敗し再読取予定の GitHub スレッド（failed と github_api_error：GitHub エラー、またはチャネルが自身の状態を読み書きできない間のローカルエラー、あるいはスレッドのタスクの一つが未完了）、公開結果、受信タスク遷移、またはポーリング結果）を記録し、メッセージテキストを含むことはありません。20件以上の通知をフィルタリングする GitHub ポーリングでは、最初の20件を個別にジャーナルに記録し、残りの数を detail.filtered でカウントする追加の reason_filter 行を1つ記録するため、固定されたポーリングカーソルが同じバッチの繰り返しでジャーナルを溢れさせることを防ぎます。カーソルが保持されている間、ポーリングが再読取したコメントはウィンドウごとに1回ずつ duplicate または mention_required としてジャーナルに記録され、失敗しているスレッドはウィンドウ内の最初の失敗ポーリング時および10回ごとの失敗ポーリング時（レート制限または認証情報エラー：その最初および10回ごと）、そしてスキップされた際に1回、github_api_error として記録されます。ウィンドウごとの行は最大8,192キーで追跡され、キーが収まらなくなった行はすべてのポーリングでジャーナルに記録されます。クエリパラメータ：limit（1-500、デフォルト100）、type（カンマ区切りの inbound、outbound、task、poll）、channel（インスタンス名ごとにパラメータを1回繰り返す）、および since（ISO 8601）。このルートにはオペレーター権限は不要です。ジャーナル読み取りは非同期かつ境界付きです：現在のジャーナルに加え、チャネルごとに1つの回転ファイル、ファイルあたり256 KiB、リクエストあたり4 MiB、リクエストあたり32ファイル、最新順。リンクメタデータは、マージされた設定の副作用のないスナップショット（いくつかの小さな JSON ファイル、ランタイムの実効環境に対して解決）を同期的に追加読み取りします。これはベストエフォートの装飾であるため、失敗時はジャーナル読み取りを失敗させるのではなくメンバーを省略します。レコード制限または任意の読み取り境界によって結果が切り捨てられた場合（ファイルごとのテールウィンドウを超える高さのジャーナルを含む）、truncated は true になります。ジャーナルがまだ存在しないワークスペースは空のリストを返します。読み取り不可のスコープディレクトリは、空のリストではなく 5xx エラーを返します。

カタログは、この管理 API でサポートされる型を manageable: true でマークします。インスタンススナップショットには、リビジョン、秘匿化されたシークレットの有無を示すメタデータ、起動状態、およびランタイム状態が含まれます。リテラルなシークレットは決して返却されません。チャネルスナップショットは Cache-Control: no-store を使用します。

フィールドディスクリプタは、properties を通じてネストされたオブジェクトメタデータを公開できます。数値ディスクリプタは、開下限のために exclusiveMinimum を、包含上限のために maximum を使用できます。新たに宣言された境界外の保存済み数値は、クライアントが変更せずに再送信する場合でも受け入れられます。したがって、境界の宣言は既存のチャネルに対する無関係な編集をブロックしません。クライアントが実際に変更した値は、両方の境界を満たす必要があります。文字列およびシークレットディスクリプタは、クライアントに複数行のテキストエリアを求めるために multiline を使用できます。ディスクリプタタイプは、トップレベルのフィールドでのみこれを許可します。広告されたフィールドの種類を描画しないクライアントは、既存の設定値を強制削除するのではなく、そのまま保持する必要があります。また、単一行コントロールで multiline フィールドを描画するクライアントは、改行を除去した入力値を書き戻すのではなく、保存された値をそのまま保持する必要があります。オブジェクトフィールドは必須にできず、ネストされたプロパティはシークレットまたは環境変数で解決可能なフィールドにできません。これらの管理プロトコルはトップレベルのみです。ネストされた required プロパティは、親オブジェクトが書き込み中に存在する場合にのみ強制されます。親オブジェクトを省略すると、そのネストされた要件はチェックされません。書き込みは各フィールドの保存値を丸ごと置き換えるため、オブジェクトを保持するには保存されたオブジェクトを再送信する必要があります。デーモンは部分オブジェクトをマージしません。

設定の書き込みは楽観的並行性と厳格なオペレーター権限ゲートを使用します。

• PUT /workspace/channels/:name
• DELETE /workspace/channels/:name
• PUT /workspace/channels/:name/startup
• 同等の/workspaces/:workspace/...ルート

各設定の変更には expectedRevision が含まれます。アップサートリクエストには config オブジェクトが含まれ、明示的なシークレット操作：preserve、replace、または clear を含む場合があります。Channel 設定は、解決されたワークスペース外の仕事用ディレクトリを選択できません。

ランタイムアクションは、POST リクエストを .../channels/:name/start、stop、または restart に厳格にゲートします。これらは解決されたワークスペースが所有するワーカーに対してのみ動作します。

ペアリング管理は、pairing 送信者ポリシーまたはグループポリシーで設定されたインスタンスでのみ利用可能です:

• GET .../channels/:name/pairing-requests
• POST .../channels/:name/pairing-requests/approveと{ "code": "..." }
• GET .../channels/:name/pairing-approvals
• { "senderId": "..." } または { "groupId": "..." } を伴う DELETE .../channels/:name/pairing-approvals

すべてのペアリングルートは厳格なオペレーター権限を必要とし、Cache-Control: no-store を使用します。リクエスト、承認、および取り消しは、選択されたチャネルインスタンスとワークスペースの範囲に限定されます。保留中のリクエストには、型付きのユーザーまたはグループのサブジェクトが含まれます。グループのリクエストには、リクエストを開始した送信者も保持されます。承認スナップショットには senderIds と groupIds が含まれます。これは許可リストが表示名を永続化しないためです。不明なユーザーまたはグループを取り消すと 404 channel_pairing_approval_not_found が返されます。

チャネル配信とNotify

channel_delivery は即時かつベストエフォートの配信サポートを広告します。これはプロトコル機能であり、ワーカーのヘルスシグナルではありません。配信は欠落しているワーカーを開始せず、別のワークスペースへのフォールバック、再試行、アウトボックスの永続化、または履歴通知の再生も行いません。

ダイレクトNotifyはAgentとSessionをバイパスし、1回の送信試行を待ちます：

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

両方のルートは厳格なミューテーションゲートを使用します。修飾されたルートは登録済みで信頼できるワークスペースのみを解決します。成功は 200 {delivered:true,deliveryId} です。delivered:true はチャネル送信 Promise が解決されたことを意味しますが、プロバイダーによる受け入れ、ユーザーによる受信、または既読レシートを保証するものではありません。IM アダプター間でのプロバイダー固有の応答検証と一貫したエラー理由セマンティクスは、この V1 契約の範囲外です。エラーは 400 channel_delivery_invalid、503 channel_worker_unavailable または channel_delivery_queue_full、504 channel_delivery_timeout、および 502 channel_delivery_rejected または channel_delivery_failed です。タイムアウトの結果は不明であり、再試行されません。意図的に個別の接続性テストエンドポイントはありません。通常の Notify 呼び出しがエンドツーエンドのテストとなります。

再生可能な結果イベントには、相関情報とサニタイズされたステータスのみが含まれます：

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

空の成功したPrompt最終レスポンスはエラーフィールドを省略します：

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

source は prompt または scheduled です。status は delivered、failed、または skipped です。skipped は、対象ターンが正常に完了したが、その最後のツールなしのアシスタント応答ブロックが空または空白のみであったことを意味します。デーモンは配信認可を消費し、イベントを公開しますが、チャネルワーカーを解決しません。スケジュールされた相関には taskId と firedAt を使用します。イベントにはターゲット ID、メッセージテキスト、認証情報、または Webhook シークレットは決して含まれません。

セキュリティ: 応答にはベアラートークン、クライアント ID、完全な ACP 接続 ID、デバイスフローのユーザーコード、または検証 URL は決して含まれません。両方の詳細レベルには追加的な daemon.runId、daemon.logMode、および daemon.logHealth が含まれる場合があります。summary はデーモンのログパスと損失の詳細を省略します。full には認証されたオペレーター向けに logPath、logIssues、logDroppedRecords、および logDroppedBytes が含まれる場合があります。劣化したファイルロギングでは、パスなしの daemon_log_degraded 警告が通常のステータスロールアップに追加されます。

GET /capabilities

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

安定した契約: v が増加する場合、フレームレイアウトは後方互換性のない方法で変更されています。

protocolVersions は、デーモンが対応できる serve プロトコルバージョンを記述します。current はデーモンの優先プロトコルバージョンであり、supported は互換性のあるセットです。特定のプロトコルを必要とするクライアントは supported を確認する必要があります。機能固有の UI は引き続き features でゲート制御を行います。v=1 に追加的: 古い v=1 デーモンはこのフィールドを省略するため、古いビルドを対象とする SDK クライアントはこれをオプションとして扱う必要があります。

Stage 1 では modelServices は常に [] です。 エージェントは単一のデフォルトモデルサービスを使用し、ワイヤー経由で列挙しません。Stage 2 では登録済みのモデルアダプターからこのフィールドを設定し、SDK クライアントがサービスピッカーを作成できるようにする予定です。それまでは、このフィールドが非空であることを前提としないでください。

workspaceCwd は、デーモンのプライマリワークスペースの正規絶対パスです。これを使用して POST /session での cwd を省略し（ルートはこのプライマリパスにフォールバックします）、古い単一ワークスペースクライアントとの互換性を維持します。v=1 に追加的: §02 より前の v=1 デーモンはこのフィールドを省略するため、古いビルドを対象とするクライアントは消費前に null チェックを行う必要があります。

workspaces[] は登録済みのすべてのランタイムを一覧表示します。新しい単一ワークスペースデーモンは、multi_workspace_sessions が存在しない場合でもプライマリラランタイムを含み、クライアントがワークスペース修飾ルートに必要な安定 ID を検出できるようにします。古いデーモンは配列を省略する場合があります。各エントリは { id, cwd, displayName?, primary, trusted, removable? } です。displayName は表示専用であり、未設定の場合は省略されます。最初の/プライマリワークスペースは workspaceCwd によってミラーリングされ続けます。新しいクライアントは、そのエントリの cwd を POST /session に渡すことで非プライマリラランタイムを選択します。信頼されていないワークスペースは診断のために広告されますが、信頼の変更まで 403 untrusted_workspace で新規セッション作成を拒否します。removable はランタイム削除をサポートするデーモンに存在し、プロセス動的または永続性復元されたセカンダリラランタイムに対してのみ true です。

session_worktree_persistence_v1 は、デーモンが Part 4A ワークツリー所有権を永続化および検証できることを意味します。成功したワークツリー作成レスポンス、およびアイドル時に再配置されたか、すでに検証済みワークツリーの cwd を報告している子を持つ復元レスポンスには、worktree メタデータと worktreeState: "persisted-v1" が含まれます。レガシーのベストエフォート復元、または parked ではなく restore-prompt が発火した cold 復元（suppressWorktreeContextRestore オフのため、ルートはブリッジに延期なしを要求しました）で、現在の cwd なしのアクティブなプロンプトを報告する場合は、その証明なしで worktree を返すことがあります。分離を要求するクライアントは、このタグをプリフライトし、各レスポンスを検証する必要があります。worktree オブジェクトだけでは永続的な所有権の証明ではありません。

session_worktree_reset_v1 は、デーモンがワークツリー所有権転送をサポートすることを意味します: POST /session/:id/worktree-reset は永続化されたワークツリーセッションのチェックアウト所有権を新しい代替セッションに移動します。復元レスポンスにはこれとともに 3 つの型付き 409 分類が含まれます: worktree_session_superseded（セッションのサイドカーに supersededBy リンクがあります — 分類はそのリンクのみから決定され、マーカー読み取りの前に行われ、リンクはマーカーが反転する前に書き込まれるため、ボディの replacementSessionId は所有権の証明ではなく検証のためのリダイレクトです: pre-commit 中断状態では、マーカー所有者ではないセッションを指し、それ自体を復元できず、再試行されたリセットによって回収されます）、worktree_marker_missing（チェックアウトマーカーが存在しません。タスクをリセットして再作成してください — 復元のリトライではできません。復元パスがマーカーを書き込むことはないため）、および worktree_reset_interrupted（以前の転送がサイドカーリンクが一致した状態で途中でクラッシュしました。リセットを再試行してください）。中断分類が最初にチェックされます: supersedes/supersededBy リンクが一致するマーカー欠落は worktree_reset_interrupted として現れ、worktree_marker_missing としては現れません。転送プロトコルと失敗分類については、以下のルートセクションを参照してください。

ワークスペース機能タグと workspaces[] は動的です。ワークスペースを追加するクライアントは、変更完了後に /capabilities を再度取得する必要があります。デーモンは以前レスポンスをキャッシュしたクライアントに機能変更をブロードキャストしません。永続性の忘却はアクティブなランタイムをアンロードしないため、そのランタイムは再起動まで広告され続けます。

GET /brand

Web Shell の製品ブランディング。シェルをホワイトレーベルしたいホスト向けです。オペレーター設定スコープ内の ui.brand から解決されます。web_shell_brand 機能タグによってゲート制御されます; このルートを持たないデーモンは 404 を返答します。

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

両方のフィールドはオプションであり、{} は正常なレスポンスです。 フィールドが存在しないことは「クライアントの内蔵ブランドを使用する」ことを意味します — Web Shell は独自の名前とインラインロゴを描画します。クライアントは空のボディをエラーとして扱ってはいけません。

ハンドラーは、設定されたロゴが拒否された場合でも常に 200 で応答します。 ファイルが存在しない場合、シンボリックリンクである場合、ハードリンクされたファイルである場合、ディレクトリである場合、SVG ドキュメントではない場合、またはコンテンツが 32 KiB を超える場合は、logoDataUri を含まないボディが返され、理由は qwen serve: GET /brand: ui.brand.logoPath … としてデーモンの stderr に書き込まれます。したがって、クライアントは「ブランドが設定されていない」と「オペレーターのロゴが拒否された」を区別できません。オペレーター向けのチャネルはデーモンログです。拒否よりも緩い警告が 2 つあります。1 つは、使用可能な viewBox と正のパーセンテージ以外の width/height (不正な形式または面積ゼロの viewBox は使用不可と見なされます) を持たないルート <svg> で、ブラウザはサイドバーの固定サイズで空白としてレンダリングする可能性があります。もう 1 つは、プレフィックスバインドされたルートであり、プレフィックスなしの要素にデフォルト名前空間バインディングがないため、それらが不可視になります。ハンドラーの前にあるミドルウェアは、実行される前に応答します — ベアラートークン認証が必要かつ存在しない場合は 401、オプションのレートリミッターが有効な場合は 429。ドレイン中のデーモンはこのルートを拒否しません: レートリミッターはドレイン中は寛容であるため、リスナーが閉じるまでハンドラーは 200 で応答し続け、クライアントは接続失敗を見ます。このルートでの起動時 503 はありません: デフォルトの遅延ランタイムパスでは、リクエストはランタイムが準備できるまで 保持 され、その後 200 で応答されるため、短いクライアントタイムアウトが早期に発火する可能性があります。code: "daemon_runtime_starting" を伴う 503 は、ランタイムが準備できる前に応答する構成 (例: --open) の場合にのみこのルートに到達し、再試行可能です。code: "daemon_runtime_failed" を伴う 503 は、デーモンが再起動するまで終端的であり、Retry-After を含みません — 再試行しないでください。

ワークスペース設定は決して寄与しません。 ルートは skipWorkspaceSettings で設定を読み込むため、リポジトリの .qwen/settings.json は製品名を変更したり、デーモンが読み取りすべての接続済みブラウザにインライン化するファイルを指定したりすることはできません。システムデフォルト、ユーザー、およびシステムのみが、その優先順位で読み取られます。同じ理由により、プレースホルダー置換によってブランド値が変更される可能性がある場合、デーモンの stderr に警告とともにブランド値が拒否されます: 置換はプロセス全体の環境から取得しますが、これはブート時にワークスペースの .qwen/.env または env ブロックによって最初に設定されます。解決できないプレースホルダー (変数が未設定) はそのまま保持されるため、誤った変数名は暗黙的にフォールバックするのではなくリテラルテキストとして表示されます。

logoDataUri は画像としてレンダリングする必要があり、マークアップとして注入してはなりません。 デーモンは読み取った SVG をサニタイズしません。img src や favicon href 経由で読み込まれた SVG はスクリプトを実行できませんが、ドキュメントに注入された SVG は実行できます。Web Shell はこれを画像コンテキストにのみ割り当て、このインベリアントがサニタイザー不在を安全にしています。

プロセスグローバル。 ルートはワークスペースセレクターもセッション ID も受け取りません: この値はユーザーグローバル設定から導出されるため、デーモンが提供するすべてのワークスペースで同じです。これは bearerAuth とレートリミッターの後、Web Shell SPA フォールバックの前に登録されるため、任意の Accept ヘッダーに対して JSON で応答します。

POST /workspaces

追加のワークスペースランタイムを登録します。パスは、他の登録済みワークスペースと重複または入れ子になっていない、既存でアクセス可能な絶対ディレクトリでなければなりません。クライアントが persist: true を送信しない限り、登録はプロセスローカルです。クライアントは永続化を要求する前に persistent_workspace_registration をプリフライトする必要があります。workspace_display_name が広告されている場合、リクエストにはオプションの displayName も含まれる場合があります。

git_workspace_clone が広告されている場合、同じルートは { "kind": "git", "url": "...", "target": "/absolute/new/path" } も受け入れます。この形式では、まだ存在しない絶対的な target が必要であり、非同期クローンを開始し、何も登録せず、202 { "kind": "git-workspace-clone", "jobId": "..." } を返します。以下の 201 および 200 の応答は、同期の cwd および scratch の形式を説明しています。git 形式は何も登録せず、クローンの進捗状況とキャンセルには GET/DELETE /workspace-git-clone-jobs/:jobId を使用します。

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

新しく作成されたランタイムは 201 を返します。すでにアクティブなセカンダリワークスペースを永続的に昇格させる場合は 200 を返します。永続的な成功には persisted: true が含まれます:

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

displayName は、前後の空白がトリムされた後に 256 文字以内の文字列でなければなりません。空の結果は名前なしとして扱われ、内部 C0 (U+0000–U+001F) または DEL (U+007F) 制御文字は拒否されます。JSON null は作成値ではなく、400 invalid_display_name を返します。初期名を提供しない場合はフィールドを省略してください。重複した表示名は許可されています。プロセスローカル登録とともに提供された名前は、そのデーモンプロセス中のみ持続します。persist: true は永続的な登録とともに保存し、再起動後に復元できるようにします。すでに永続的なワークスペースに対するリクエストの繰り返しは冪等であり、名前を変更しません。

エラーには 400 invalid_path / invalid_persist_flag / invalid_persist_target / invalid_display_name, 409 workspace_exists / workspace_nested / workspace_limit_reached / workspace_registration_store_too_large, 500 workspace_registration_store_error / runtime_creation_failed, および 501 persistence_not_available / not_implemented が含まれます。

PATCH /workspaces/:workspace

ワークスペース ID または URL エンコードされた絶対 cwd によって選択されたアクティブなワークスペースリソースを更新します。エンドポイントは現在、表示名メタデータのみをサポートしています:

{ "displayName": "Payments Production" }

名前をクリアするには { "displayName": null } を送信します。ここで null は更新専用削除センチネルです。null 以外の値は POST /workspaces と同じ文字列正規化ルールに従います。応答は更新された { id, cwd, displayName?, primary, trusted, removable? } ワークスペースプロジェクションです。ランタイムメタデータは常に更新されます。ランタイムが一致する永続的な登録アイデンティティを持つ場合、すべてのエイリアスは既存のスキーマ v1 登録ストアを通じてアトミックに更新されます。エンドポイントが永続的な登録を作成または昇格することはありません。

サポートされていないフィールドは、暗黙的に無視されるのではなくフェイルクローズします。エラーには 400 empty_patch / invalid_display_name / unsupported_field / workspace_mismatch, 409 workspace_registration_in_progress, 500 workspace_registration_store_error, および 503 daemon_shutting_down が含まれます。

DELETE /workspaces/:workspace

削除可能なセカンダリランタイムを 1 つ削除します。セレクターは複数形ワークスペースルーティングルールに従い、ワークスペース ID または URL エンコードされた絶対 cwd のいずれかを受け入れます。オプションの JSON ボディは { "force": boolean } です。省略すると強制でない削除を要求します。

凍結されたランタイムにセッション、プロンプト、保留中の開始、ACP 接続、メモリタスク、またはワークスペースチャネルワーカーがある場合、強制でない削除は activity スナップショット付きの 409 workspace_busy を返します。{ "force": true } を送信すると、これらのリソースの終了を要求します。永続的な削除はコミットポイントです: その後のクリーンアップは制限付きかつベストエフォートであり、クリーンアップの失敗はログに記録され、論理的な削除はランタイムを復元する代わりに依然として収束します。成功した応答は次のとおりです:

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

即時ビジー状態の強制でないリクエストは、高速なプレドレイン活動スナップショットを返します。ドレインが開始されると、ビジーまたは成功の応答には、アドミッションと ACP ドレインゲートが閉じた後、クリーンアップが開始される前に取得された最終スナップショットが含まれます。エラーには 400 invalid_force_flag / workspace_mismatch, 409 workspace_busy / primary_workspace_removal_forbidden / static_workspace_removal_forbidden / workspace_removal_in_progress / workspace_registration_in_progress, 500 workspace_persist_failed / workspace_runtime_removal_failed, 501 workspace_runtime_removal_unsupported, および 503 daemon_shutting_down が含まれます。

GET /workspace-registrations

このプライマリワークスペース用に永続化された望ましいワークスペースセットを一覧表示します。現在の起動中に保存されたディレクトリを復元できなかった場合、エントリは active: false で表示されたままになります。ランタイムがライブリソースを所有し続けるため、削除が完了するまでランタイムがドレイン中である間、エントリは active: true のままです。永続的な登録に存在する場合、エントリにはオプションの displayName が含まれます。

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

登録ストアが設定されていない場合は 501 persistence_not_available を返し、ストアを読み取れない場合は 500 workspace_registration_store_error を返します。

DELETE /workspace-registrations/:id

永続化された登録を1つ破棄します。これはアクティブなランタイムをアンロードしたり、そのセッションを終了したりしません。restartRequired: true は、アクティブなランタイムが次回のデーモン再起動時に消滅することを意味します。

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

404 workspace_registration_not_found、500 workspace_registration_store_error、または 501 persistence_not_available を返します。他の変更ルートと同様に、デーモン認証が有効な場合、このエンドポイントには変更認証が必要です。

読み取り専用のランタイムステータスルート

これらのルートはデーモン側のランタイムスナップショットを報告します。これらは追加的な v1 ルートであり、状態を変更せず、serve プロトコルのバージョンも変更しません。ワークスペースステータスルートは、クライアントが GET ルートをポーリングするという理由だけで ACP 子プロセスを開始することを意図して しません。GET /workspace/mcp は、デーモンがアイドル状態で保持されている MCP 観測結果を持たない場合、空のスナップショットを含む initialized: false を返します。ライブの子プロセスが以前に応答した場合、アイドル時の読み取りはその観測結果を source: "cache" と元の initialized 値で再生します。GET /workspace/skills は代わりに保持されたデーモン観測結果またはデーモンローカル列挙を提供し、保持された観測結果が存在せず、両方のソースが利用できない場合（またはコールド読み取りがスロットリングされている場合）にのみ、errors エントリ付きの initialized: false （再利用可能なカタログではなく、再試行可能な利用不可）を報告します — GET /workspace/skills を参照してください。GET /workspace/providers はワークスペース設定と環境からデーモンローカルに応答されるため、ライブの ACP 子プロセスに依存せず、acpChannelLive はライブネスを報告します。その initialized は成功パスでは true であり、ワークスペース設定またはモデル構成を解決できない場合は errors エントリ付きの false です。デーモンローカルプロバイダービルダーなしで構築されたデーモンはライブ ACP スナップショットにフォールバックし、デーモンローカルの応答にはランタイムに登録されたモデルが含まれません。セッションステータスルートはライブセッションを必要とし、不明な ID に対しては 404 { code: "session_not_found", ... } を返します。

機能タグ：

• workspace_mcp → GET /workspace/mcp
• workspace_skills → GET /workspace/skills
• workspace_providers → GET /workspace/providers
• workspace_acp_status → GET /workspace/acp/status
• workspace_env → GET /workspace/env
• workspace_preflight → GET /workspace/preflight
• session_context → GET /session/:id/context
• session_supported_commands → GET /session/:id/supported-commands
• session_tasks → GET /session/:id/tasks
• session_resources → GET /session/:id/resources
• session_monitor_tool_correlation → GET /session/:id/tasks からのモニターエントリには、トランスクリプトからタスクへの相関のために toolUseId が含まれます
• session_status → GET /session/:id/status
• session_info → GET /workspace/:id/session-info および GET /workspaces/:workspace/session-info
• session_transcript → GET /session/:id/transcript
• workspace_persisted_transcript → GET /workspaces/:workspace/session/:id/transcript
• workspace_session_export → GET /workspaces/:workspace/session/:id/export
• workspace_archived_session_export → GET /workspaces/:workspace/session/:id/archive/export
• workspace_session_live_state → GET /workspaces/:workspace/sessions/live-state
• workspace_qualified_memory → POST /workspaces/:workspace/memory/{remember,forget,dream} および GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId

workspace_acp_status はプライマリワークスペースの ACP チャネルの時点でのライブネスを { channelLive: boolean } として報告します。ハンドラーはチャネルを作成しませんが、ランタイムルートに到達すると、遅延デーモンランタイムが最初に開始される場合があり、その設定された起動ポリシーは独立して ACP をプリヒートする可能性があります。スナップショットはリースではありません。クライアントはセッション作成時にチャネルの再検証または開始を許可する必要があります。

ACP 予熱

機能タグ: workspace_acp_preheat.

POST /workspace/acp/preheat?timeoutMs=N はプライマリワークスペースの ACP チャネルをベストエフォートで初期化します。timeoutMs のデフォルトは 5000 であり、60000 以下でなければならない正の整数です。並行する呼び出し側とセッション作成は同じブリッジ初期化を共有します。リクエストタイムアウトはその HTTP 待機のみを終了させ、共有初期化をキャンセルしません。

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

ready は常に channelLive と等しい。ライブの応答では reason と error が省略され、それ以外の場合 reason は timeout または error となる。durationMs は現在の HTTP 呼び出しを測定するものであり、その呼び出しが参加した初期化全体のライフサイクルではない。運用上のタイムアウトまたは失敗は HTTP 200 を返す。無効な timeoutMs は 400 を返すが、認証、レート制限、遅延実行の失敗は通常の応答を維持する。

両方の ACP ワークスペースルートは単数形で、プライマリワークスペース専用である。クライアントはこれらをセカンダリワークスペースで使用したり、いずれかの応答を持続的な準備完了保証として解釈したりしてはならない。

共通のステータスセル:

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

errorKind は /workspace/preflight、/workspace/env、および（将来的には）MCP ガードレールで共有される閉じた列挙型であり、SDK クライアントが自由形式のメッセージを解析する代わりにカテゴリごとに修復措置を描画できるようにする。元の 7 つのステータスリテラルは #4175 に由来し、restore_timeout はセッション復元リクエスト用に別途追加された。blocked_egress は egress プローブが実装されるまで予約されたままとなる。

ステータスのペイロードには、MCP の環境変数の値、ヘッダー、OAuth/サービスアカウントの詳細、プロバイダー API キー、プロバイダーの baseUrl / envKey、スキル本体、スキルのファイルシステムパス、フック定義、シークレット環境変数の値は決して公開されない。/workspace/env はホワイトリストに登録された環境変数の存在のみを報告する。プロキシ URL は資格情報を削除され、送信前に host:port に縮約される。

GET /workspace/mcp

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

discoveryState は not_started、in_progress、または completed のいずれかである。transport は stdio、sse、http、websocket、sdk、または unknown のいずれかである。errors は検出が成功した場合に省略される。

source は、観測結果を生成した子プロセスが生きている間 "live" である。デーモンがアイドル状態で、生きている子プロセスが以前に応答した場合、応答はその観測結果を source: "cache" および子プロセスの元の値（initialized: true とそのサーバーリストを含む）で再生する。キャッシュされた観測結果は、新しい MCP 検出が始まったときのみクリアされる。子プロセスの回収によって破棄されるわけではないため、アイドル状態の GET /workspace/mcp は現在生きている子プロセスが提供していないカタログを報告する場合がある。

MCP クライアントのガードレール (issue #4175 )。 現在のデーモンはペイロードに 4 つの追加フィールドと capability-scoped budget cell を拡張します:

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

budgetMode は enforce、warn、または off のいずれかです。予算が設定されていない場合、clientBudget は存在しません。mcp_guardrails を広告するデーモンでは、budgets[] は 常に配列 です（budgetMode === 'off' の場合は空になる可能性あり）。古いデーモンはこのフィールド自体を省略します。mcp_workspace_pool が広告されている場合、cell には scope: 'workspace' が含まれ、選択されたワークスペースランタイムの共有プールをカバーします。そのタグが存在しない場合（QWEN_SERVE_NO_MCP_POOL=1 の下も含む）、レガシーマネージャーは scope: 'session' を出力します。コンシューマーは、認識できないスコープ値の追加を必ず許容する必要があります。

サーバーごとの cell における disabledReason は、オペレーターによる無効化（'config' — disabledMcpServers 設定リスト）と、予算による拒否（'budget' — 検出されたものの、enforce モードにより接続されなかった）を区別します。拒否は Object.entries(mcpServers) の宣言順によって決定論的です。サーバーごとの status: 'error', errorKind: 'budget_exhausted' は、生の mcpStatus: 'disconnected'（true だがオペレーター向けの深刻度ではない）をシャドウします。

予算の強制実行は capability-driven です。mcp_workspace_pool を使用すると、1 つのワークスペースランタイム内のセッションはトランスポートと 1 つの WorkspaceMcpBudget を共有します。異なるワークスペースランタイムはプールや予算を共有しません。このタグがない場合、各 ACP セッションの McpClientManager は上限のコピーを独自に強制実行し、スナップショットはそのレガシーセッションビューを表します。

予算圧力の検出。 PR-14b 以降で両方のサーフェスが利用可能になります:

• プッシュイベント（mcp_guardrail_events で広告）: GET /session/:id/events を購読し、KnownDaemonEvent を通じて mcp_budget_warning / mcp_child_refused_batch フレームを絞り込みます。ステートマシンは上昇時の 75% 交差ごとに一度発火します（37.5% 未満で再アーム）。拒否は enforce モード下でディスカバリーパスごとに一度まとめられます。

• スナップショットポーリング（mcp_guardrails で広告）: GET /workspace/mcp を実行し、budget cell（budgets[0]）と mcp_workspace_pool を調べてそのスコープを判定します:

• budgets[0].status === 'warning' ⇔ liveCount >= 0.75 * clientBudget （PR 14b のヒステリシス閾値と一致し、プッシュイベントで使用されます）。

• 推奨ポーリング頻度：budgets[0].status === 'error'を既にポーリングしているものに合わせます；スナップショットは軽量であり、予算セルは追加のディスカバリーコストを伴いません。プッシュイベントを購読するSDKクライアントも、長時間切断後の状態確認のためにスナップショットから利益を得られます（SSE再生リングの深さは有限です — refusedCount > 0、デフォルト8000 — そのため、リングのカバー範囲より長くオフラインだったクライアントはスナップショット再同期にフォールバックします）。

• budgets[0].status === 'ok' ⇔ 75% 閾値未満かつ拒否なし。

推奨されるポーリング間隔: /workspace/mcp をすでにポーリングしているものに合わせます。スナップショットは軽量で、budget cell には追加のディスカバリーコストはありません。プッシュイベントを購読する SDK クライアントも、長時間の切断後の状態確認のためにスナップショットから利益を得られます（SSE リプレイリングの深さは有限であり、--event-ring-size、デフォルト 8000 — したがって、リングのカバー範囲より長くオフラインになったクライアントはスナップショット再同期にフォールバックします）。

GET /workspace/skills

プライマリとワークスペース修飾付きのインベントリルートは、バックグラウンドで再検証しながら保持されたスナップショットを即座に返す。開始はタスク開始から計測され、1 秒に 1 回にスロットルされ、同時読み取りはタスクを共有する。ウォームバックグラウンド再検証は 5 秒後にスロットを解放する。タイムアウトは再試行を許可するが、観測または ACP 作業を取り消さない。コールド読み取りは、ACP で設定されたリクエストタイムアウト（デフォルトで 10 秒）、その後 ACP が利用できない場合のデーモンローカル列挙に従う。どちらのソースにもバックグラウンド期限を課さない。開始から 1 秒以内に失敗したコールド読み取りは、そのウィンドウの残りの部分を即座に利用不可ステータスで返す。より遅い失敗はスロットルウィンドウを残さないため、クライアント側で独自の再試行バックオフが必要になる。遅れて成功したバックグラウンド観測は再試行が保留中に公開できるが、すでに公開されている後から開始された観測を置き換えることはできない。無効化されたタスクは公開できない。無効化された観測が成功しても、元の呼び出し元に回答することはできる。明示的な無効化は既知の無効なインベントリを破棄し、スロットルをクリアする。タイムアウト前に完了した ACP プリヒートの成功も保持されたインベントリを無効化する。これは子プロセスがすでに生きている場合も含み、その後の読み取りで子プロセスが見えるようにする。タイムアウトしてからチャネルが生きていることを発見したプリヒートも ready: true を報告する — ready は常に channelLive と等しい — が、起動がまだ不完全な可能性があるため保持されたインベントリを維持する。次の読み取りはその保持データを返し、1 秒の開始スロットルが許可されるとバックグラウンド再検証がそれを置き換える。スキル削除はスナップショットとスロットルをバイパスするが、新しく列挙されたカタログが必要であり、ローカルフォールバックを使用し、保持されたスナップショットから応答することはない。有効化アイデンティティ読み取りはスナップショットとスロットルをバイパスし、新しい観測を待機し、両方のソースが失敗した場合はローカルフォールバック、次に保持されたスナップショットを使用する。

保持されたデーモン観測を含むインベントリアクティブには、オプションのスナップショットメタデータが追加で含まれる。直接の設定/ランタイムステータス読み取り、セッションリソースインベントリ、古いデーモンはこれを省略する。上書きされた成功したコールド読み取りは、利用可能な場合、より新しい保持されたスナップショットを返す。そうでない場合、このメタデータなしで自身のキャッシュされていない観測結果を返す。エラーのない初期化された観測結果のみが保持されたスナップショットを置き換えることができる:

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

observedAt は、正常な観測の Unix ミリ秒単位の開始時刻です。ageMs は応答ごとに再計算され、収集時間を保守的に含みます。stale は、その観測が少なくとも 1 秒経過していることを意味します。refreshing は、再検証が共有スロットを占有しているかどうかを報告します。タイムアウトした観測は、スロットが解放された後も完了する場合があります。読み取り失敗、スロットのタイムアウト、およびランタイム停止後のリプレイはタイムスタンプを更新しません。後続の正常な公開は、独自の観測開始時刻を記録します。クライアントはこの経過時間を表示できますが、これはファイルシステムのリビジョンではなく、すべてのセッションが最新であることを保証するものではありません。初期化されたスナップショットが存在せず、両方のソースが利用できない場合（またはコールド読み取りがスロットリングされている場合）、応答には initialized: false、errors エントリが含まれ、snapshot メタデータはありません。これは再試行可能な一時的な利用不可であり、空のカatalogではありません。有効な空のカatalog は initialized: true を持ちます。ステータスの読み取りでは、セッションに影響を与える Skill の更新コマンドは呼び出されません。閉じた状態またはドレイン中のワークスペースランタイムは読み取りを拒否します。保持されたデータは、子チャネルの除去では生き残りますが、ランタイムの退役では失われます。

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

level は project、user、extension、または bundled のいずれかです。userInvocable（ブール値、省略可能）は通常のスキルに対しては省略されます（true を意味します）。手動で呼び出せないスキルの場合のみ false として存在します。これは、以下で説明する設定専用の Skill トグルルートを制御するものではありません。modelInvocable は独立しています。false は、スキルが手動では引き続き利用可能ですが、モデルからの呼び出しからは隠されることを意味します。installedPath は、スキルの SKILL.md への既存の絶対パスです。デーモンはこれを保存されたまま返し、シンボリックリンクの個別解決や正規化は行いません。現在のデーモンはすべてのスキルに対してこれを出力しますが、クライアントは古い v1 デーモンからの欠如を許容する必要があります。スキル本体、フック、skillRoot、およびその他のスキル設定は除外されたままです。検出が成功した場合、errors は省略されます。

拡張機能所有のスキルの場合、extensionName は正規化されたマニフェスト名であり、所有者識別子として安全に使用できます。extensionDisplayName はオプションのローカライズされた表示用値であり、一意ではない可能性があります。新しいクライアントは extensionDisplayName ?? extensionName を表示すべきです。古いデーモンは表示フィールドを省略します。

繰り返しの読み取りは、最後にコミットされたワークスペーススナップショットから提供され、子のメモリ内キャッシュに対して定期的に再検証されます。定常状態の読み取りでは、スキルディレクトリのスキャンや SKILL.md ファイルの再解析は行われません。コールドなデーモンローカルフォールバックはディスクから列挙を行うことができます。子は、拡張機能のソースが変更されていないことを確認します。具体的には、拡張機能ディレクトリの readdir と各エントリの stat、有効化ファイル、およびストアのアクティベーション状態を確認し、それらが移動した場合のみ更新します。そのため、デーモンの外でインストールまたはトグルされた拡張機能は、再検証によって拾い上げられ、その再検証が公開された後の subsequent な読み取りに表示されます。ウォーム読み取りは、バックグラウンド作業を開始する場合でも、常に保持された観測結果を返します。セーフモードとベアモードはこのチェックをスキップし、拡張機能を除外する動作と一致させます。

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

モデルは認証タイプ別にグループ化されています。プロバイダー接続診断情報は /workspace/preflight の providers セルにあります。環境プリフライト情報は /workspace/preflight と /workspace/env にあります（以下参照）。スナップショット構築が成功した場合、errors は省略されます。

GET /workspace/env

デーモンプロセスのランタイム、プラットフォーム、サンドボックス、プロキシ、およびホワイトリストに登録された秘密環境変数の存在を報告します。常に process.* の状態から回答します。デーモンがこのルートを提供するために ACP 子を起動することは決してなく、ACP が稼働中であってもアイドル状態であっても応答は同一です。acpChannelLive フィールドは情報提供のみを目的としています。

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

セル形状:

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

編集ポリシー。 kind: 'env_var' セルには value フィールドが決して含まれません。クライアントは present: boolean のみを見ます。kind: 'proxy' セルでは、生の環境変数値が資格情報編集処理（redactProxyCredentials）を通り、その後 URL 解析を通るため、ワイヤー上には host:port のみが載ります。NO_PROXY は URL ではなくホストリストであるため、編集処理をそのまま通過します。現在列挙されている秘密環境変数のホワイトリストには、OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY、GOOGLE_API_KEY、DASHSCOPE_API_KEY、OPENROUTER_API_KEY、および QWEN_SERVER_TOKEN が含まれます。他の環境変数は列挙されないため、誤って設定された秘密情報は見えなくなります。

GET /workspace/preflight

デーモンの準備完了チェックを報告します。デーモンレベルのセル（node_version、cli_entry、workspace_dir、ripgrep、git、npm）は常に process.* と node:fs から入力されます。ACP レベルのセル（auth、mcp_discovery、skills、providers、tool_registry、egress）はライブの ACP 子を必要とし、デーモンがアイドル状態の場合は status: 'not_started' プレースホルダを出力します。このルートはセルを入力するためだけに ACP を起動することはありません。対応するセルは not_started にフォールバックします。

アイドル時の応答（ACP 子なし）:

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

セル形状:

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

errorKind のセマンティクス:

• missing_binary — Node バージョンが必須より低い、QWEN_CLI_ENTRY の欠如、ripgrep / git / npm が PATH にない（オプションのバイナリについてはエラーではなく警告）。
• missing_file — boundWorkspace が存在しないかディレクトリではない。欠落または読み取り不能なファイルを指すスキル解析エラー。
• parse_error — SKILL.md 解析失敗、不正な設定 JSON。
• auth_env_error — validateAuthMethod が null 以外の失敗文字列を返したか、プロバイダー解決から伝播された ModelConfigError サブクラス。
• init_timeout — ブリッジ内の withTimeout リジェクト（ACP ラウンドトリップ待機中の実際のタイムアウト）。BridgeTimeoutError 型付きクラスによって認識されます。注意：connecting > 0 を持つ一時的な mcp_discovery warning セルはこの種類を含みません。これは進行中のハンドシェイクの通常の状態であり、実際のタイムアウトとは区別されます。
• restore_timeout — セッションの読み込みまたは再開が、専用の復元予算を超えました。REST レスポンスは 504 であり、再試行可能です。これは子プロセスの初期化や、制限付き再生ウィンドウの上限とは異なります。
• protocol_error — リクエスト中にチャネルが閉じられたため、またはツールレジストリが予期せず存在しなかったため、ACP extMethod が拒否されました。
• blocked_egress — PR 14 (#4175) 用に予約されています。PR 13 では egress セルを status: 'not_started' のままにしています。

プリフライトリクエストの処理中にブリッジが ACP 子プロセスに到達できなかった場合（例：リクエスト中のチャネルクローズ）、エンベロープの errors 配列には障害を示す単一の ServeStatusCell が含まれ、セルは not_started ACP プレースホルダーにフォールバックします。デーモンレベルのセルは引き続き返されます。

GET /workspace/tools

プライマリワークスペースの ACP 子プロセスから報告されたツールカタログを返します。これはレガシーなプライマリワークスぺースルートです。ワークスペースセレクターがなく、非プライマリランタイムのツールを推測するために使用してはいけません。

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

アクティブな ACP 子プロセスがない場合でも、ルートは 200 を返し、acpChannelLive: false、空の tools 配列、およびオプションの errors 配列内の not_started エントリを含みます。予期しないブリッジ障害は標準的な 500 ブリッジエラーレスポンスを使用します。TypeScript SDK メソッドは workspaceTools() です。専用の機能タグはないため、古いデーモンをサポートするクライアントは 404 を未対応として扱う必要があります。

ワークスペースファイルルート

レガシーファイルルートはプライマリワークスペースを通じてパスを解決します。/workspaces/:workspace/... ルートは選択されたランタイムのワークスペースを通じてパスを解決します。レスポンスはワークスペース相対パスを使用し、通常の成功ケースでは絶対ファイルシステムパスを返しません。成功したファイルレスポンスには以下が含まれます:

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

ファイルシステムエラーはこの JSON 形式を使用します:

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

errorKind の値には path_outside_workspace、symlink_escape、path_not_found、binary_file、file_too_large、untrusted_workspace、permission_denied、parse_error、hash_mismatch、file_already_exists、text_not_found、および ambiguous_text_match が含まれます。

GET /file

テキストファイルを読み取ります。クエリパラメータ: path (必須)、maxBytes、line、limit、および cursor。デーモンはバイナリファイルを拒否します。256 KiB のフルスナップショット上限を超えるファイルには、少なくとも 1 つの明示的なウィンドウ引数（line、limit、または maxBytes）が必要です。これらが指定されていないリクエストは file_too_large のままになります。そのようなウィンドウはストリーミングされ、返される UTF-8 コンテンツは 256 KiB に制限されます。maxBytes は常にデコード後の UTF-8 レスポンスバイトに適用され、ソースがフルスナップショット上限内で他のサポートされているエンコーディングを使用している場合も含みます。

行オフセットはファイルの先頭からのスキャンによって解決されるため、ウィンドウへの到達に 8 MiB 以上（MAX_TEXT_SCAN_BYTES）を読む必要がある場合は file_too_large で拒否されます。より深いオフセットに直接到達するには GET /file/bytes を使用してください。ルートがデコードできないエンコーディングの大きなテキストは binary_file を返し、file_too_large を返しません — より小さなウィンドウで再試行しても助けにはならず、readBytes はバイナリに既に適用されている同じ対策です。

フルスナップショット上限内のファイルの場合、レスポンスには hash が含まれます。これはファイル全体の生ディスク上のバイトに対する SHA-256 ダイジェストであり、line、limit、または maxBytes がスライスを返した場合でも同様です。大きな部分ウィンドウでは hash を省略し、完全な sizeBytes を保持し、truncated: true を設定し、ストリームが EOF 前に停止した場合は originalLineCount: null を返します。

cursor によるページング

workspace_file_read_cursor 機能が必要です。さらにデータがあるレスポンスは hasMore: true を返し、ファイルバイトオフセットが導出可能な場合は nextCursor トークンを返します。これを cursor として渡すと O(1) で再開できますが、深い line オフセットはバイト 0 からのスキャンが必要になり、8 MiB を超えると拒否されます。

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

cursor と line は相互排他的です（parse_error）— どちらも開始点を指定します。不正な形式または長すぎるカーソルは parse_error です。ファイルが置き換えられたり切り詰められたりしたカーソルは hash_mismatch (409) です。追加操作は未完了のカーソルを無効化しません。これがこの機能が存在する理由です。

content は他のすべての読み取りと同様に、最後の行の終端改行を省略するため、ページを再組み立てするクライアントはそれらを \n で結合します。hasMore は nextCursor の言い換えではありません: limit を使用して読み取られた小さな非 UTF-8 ファイルにはコンテンツが多いですが、導出可能なバイトオフセットがないため、hasMore: true を nextCursor: null とともに報告します。バイト上限が現在の行を切断する場合もカーソルは null になります。そのオフセットから再開すると部分的な行が返されるからです。多くの短い行がある場合、ページがバイト上限の前に終わり、カーソルを返すまで limit を下げてください。単一の巨大な行がある場合、次の行を明示的に要求してください（例えば、1 行目から開始する場合は line=2）。その後カーソルで続けます。完全な巨大な行が必要な場合は GET /file/bytes を使用してください。

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

GET /file/bytes

デコードせずにファイルから生バイトを読み取ります。クエリパラメータ: path (必須)、offset (デフォルト 0)、および maxBytes (デフォルト 65536、最大 262144)。このルートは、ファイル全体を一括読み込みすることなく、大きなバイナリファイルに対する制限付きウィンドウをサポートします。レスポンスには、返されたウィンドウがファイル全体をカバーする場合のみ hash が含まれます。

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

GET /stat

プライマリワークスペースの 1 つのパスのメタデータを返します。クエリパラメータ path は必須です。

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

type は file、directory、symlink、または other です。ルートはワークスペースファイル境界と、上記で説明した共通のファイルシステムエラーエンベロープを使用します。TypeScript SDK メソッドは fileStat() です。

GET /list

プライマリワークスペースのディレクトリを1つ一覧表示します。クエリパラメータ path は必須です。includeIgnored=1（または true）を指定すると、無視ルールに一致するエントリが含まれます。レスポンスは最大 2,000 エントリに制限され、それ以上存在する場合は truncated: true が設定されます。

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

各エントリの kind は file、directory、symlink、または other です。TypeScript SDK メソッドは dirList() です。

GET /glob

プライマリワークスペース内のパスを検索します。クエリパラメータ pattern は必須です。オプションの cwd で検索範囲を絞り込み、includeIgnored=1（または true）で無視されたパスを含め、maxResults は 1 から 50,000 の整数（デフォルトは 5,000）です。

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

一致結果はワークスペース相対です。無効なクエリ値は 400 を返します。ワークスペース信頼性、包含関係、パス欠落、予期しない失敗には共通のファイルシステムエラーエンベロープが使用されます。TypeScript SDK メソッドは glob() です。

POST /file/write

テキストファイルを作成または置き換えます。これは厳密な変更ルートです：トークンなしの信頼できるループバックからのプライマリリクエストは許可されます。信頼できるループバック権限なしでゲートに到達したトークンなしのプライマリリクエストは 401 { "code": "token_required" } を返します。設定されたトークンおよび Local Control 認証情報の失敗は、より早い段階で単純な 401 Unauthorized で拒否されます。--require-auth の場合、グローバルベアラミドルウェアがルート実行前に未認証のリクエストを拒否します。

ボディ:

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

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

mode は create または replace でなければなりません。create は既存のファイルを上書きしません（409 file_already_exists）。replace は expectedHash を必要とします。ハッシュが存在しないか不正な形式の場合は 400 parse_error、古いハッシュの場合は 409 hash_mismatch です。expectedHash は sha256: に小文字の16進数64桁を追加したもので、ディスク上の生バイトに対して計算されます。

bom、encoding、および lineEnding を指定できます。置き換え時は、デフォルトで既存ファイルのエンコーディングプロファイルを保持し、明示的なフィールドで上書きします。バイナリ書き込みは対象外です。

デーモンはターゲットディレクトリ内のランダムな一時ファイルに書き込み、サポートされている場合は fsync を実行し、rename() の直前に現在のハッシュを再チェックしてから、名前を変更して配置します。これにより部分的なファイル観察を防ぎ、同じファイルへのデーモン由来の書き込みをシリアル化しますが、プロセス間カーネル比較スワップではありません：最終ハッシュチェックと名前変更の間のわずかなウィンドウで外部エディタが競合する可能性があります。

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

POST /file/edit

既存のテキストファイルに正確なテキスト置換を1回適用します。これも厳密な変更ルートであり、expectedHash が必要です。

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

oldText は空ではなく、完全に一度だけ出現しなければなりません。一致がない場合は 422 text_not_found、複数一致する場合は 422 ambiguous_text_match を返します。ルートはエンコーディング、BOM、改行コードを保持し、アトミックな名前変更の直前に expectedHash を再チェックします。

無視されたパスへの明示的な書き込み/編集は、認証された呼び出し元がパスを指定しているため許可されます。成功レスポンスと監査イベントには matchedIgnore: "file" | "directory" | null が含まれます。

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

POST /workspaces/:workspace/directory/create

workspace_qualified_rest_core と workspace_directory_create、厳密な変更権限、および信頼できるアクティブなローカルワークスペースが必要です。ボディ:

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

親が存在する必要があります。作成は排他的です：既存のファイルまたはディレクトリがある場合は 409 file_already_exists、最終的なシンボリックリンクの場合は 400 symlink_escape を返します。成功は 201 { "kind": "directory_create", "path": "src/new-folder" } です。SDK メソッドは WorkspaceDaemonClient.createWorkspaceDirectory(path, clientId?) です。

POST /workspaces/:workspace/directory/delete

同じ厳密な変更および信頼できるローカルランタイムポリシーの下で、workspace_qualified_rest_core と workspace_directory_delete が必要です。ボディ:

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

空または非空のディレクトリを再帰的に削除します。ワークスペースルート、通常ファイル、最終的なシンボリックリンクは拒否されます。入れ子のシンボリックリンクエントリは、ターゲットを追跡せずに削除されます。ターゲットが存在しない場合は 404 path_not_found を返します。成功は 200 { "kind": "directory_delete", "path": "src/old-folder" } です。SDK メソッドは WorkspaceDaemonClient.deleteWorkspaceDirectory(path, clientId?) です。

両方のディレクトリルートは、選択されたワークスペース内で親を解決しながら、語彙上の最終名を保持します。パスは区切り文字で終わってはなりません。不審なパスパターンは 400 path_outside_workspace を返し、不正なリーフ形状は 400 parse_error を返します。サポートされていないカスタムファクトリは 422 を返します。SSH ワークスペースは SSH 境界によって 501 で拒否されます。不明、利用不可、削除済み、または信頼できないオーナーはプライマリにフォールバックしません。

削除は永久的であり、失敗時に部分的な削除が残る可能性があります。並行ライターが ENOTEMPTY を引き起こすことがあり、503 io_error として返されます。ライターが停止した後、同じ操作を再試行してください。パスごとのロックはディレクトリをすべての子書き込みに対してシリアル化せず、外部ディレクトリ置換は移植可能なパスベースのチェックではアトミックにできません。無視されたディレクトリへの明示的な変更は許可され、該当する場合、監査イベントは matchedIgnore を注釈付けします。作成記録は sizeBytes: 0 です。

GET /session/:id/context

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

トップレベルセッションの場合、state は POST /session、POST /session/:id/load、および POST /session/:id/resume で使用される同じ ACP モデル/モード/設定オプションの形状を反映します。subagent. プレフィックス付きの仮想セッション ID はその親ランタイムに対して解決され、空の state オブジェクトを返します。

GET /session/:id/supported-commands

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

availableCommands は available_commands_update SSE 通知で使用される同じコマンドスナップショットです。availableSkills はスキル名のみを一覧表示します。クライアントはこのルート経由でスキル本体やパスを期待してはなりません。

GET /session/:id/tasks

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

このルートは読み取り専用のアウトオブバンドスナップショットです。意図的にプロンプトではなく、セッションがストリーミング中に照会できます。レスポンスにはエージェント、シェル、モニタータスクレジストリからのホワイトリスト化されたメタデータのみが含まれ、コントローラー、タイマー、オフセット、保留中のメッセージ、生のレジストリオブジェクトは公開されません。

別のサブエージェントによって生成されたエージェントタスク（ネストされたサブエージェント、maxSubagentDepthで制限）には、3つのオプションの系譜フィールドが含まれます: parentAgentId（生成元のエージェントタスクのid）、parentName（登録時にキャプチャされるため、親がレジストリから退避されても保持される、生成元エージェントのsubagentType）、およびdepth（0ベースの起動深さ; 0 = トップレベルセッションによって生成）。トップレベルセッションによって起動されたエージェントはparentAgentIdとparentNameを省略します。クライアントはこれら3つのフィールドすべてをオプションとして扱い、存在しない場合はフラットなリストにフォールバックする必要があります。

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

1つのシェルタスク用のオンデマンド詳細。GET /session/:id/tasksはライフサイクル事実のみを含みます。このルートはキャプチャされた出力ファイルを読み取り、プロセスツリーをプローブするため、開いている詳細パネルはこれを個別に要求します。

ACPメソッドは_qwen/session/task_runtimeで、sessionIdとtaskIdのパラメータを持ちます。両方のトランスポートはライブセッションオーナーを解決し、ACPでは接続がセッションを所有していることも必要です。

パスのtaskIdは、セッション自身のシェルレジストリに対して解決されます。呼び出し側はファイルパスを渡しません。

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

タスクが不明な場合、退避された場合、またはシェルタスクでない場合、runtimeはnullです。memoryBytesはシェルのプロセスツリーの常駐セットで、タスクの実行中のみサンプリングされます。共有ページはプロセスごとに1回カウントされ、コンテナサンドボックスはラッパープロセスのみを公開する場合があります。outputTailは完了通知で使用される同じ8 KiBの上限で制限され、outputTailTruncatedはファイルの途中で始まる末尾を示します。ファイルが読み取れない場合、outputErrorが設定されます。成功した部分からのフィールドはまだ存在する可能性があります。

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

ワークフロー実行を制御するか、新しい実行を開始します。ACPメソッドは_qwen/session/tasks/workflow_actionです。

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

taskId が何を指すかはアクションによります:

args、sourceRef、およびscriptはrun-savedとrun-scriptによってのみ読み取られます。argsはスクリプトのargsグローバルにバインドされ、任意のJSON値を取り得ます。sourceRefは呼び出し側の独自の{id, revision}で、実行、そのジャーナル、およびそのスナップショットに記録されます。scriptはソースrun-scriptが実行するものであり、それによって必須とされます。リトライまたは再実行は、元の独自の実行のargsとsourceRefを再生します。これが同じ実行であることを保証するため、これらのフィールドは制御アクションとともに無視されます。

開始された実行はセッション所有です。承認プロンプトなしでバックグラウンドで実行され、その完了はセッションの完了チャネルに到達します。その後、他の実行と同様にretry/rerunターゲットになります。

retryとrerunは、履歴から復元された実行（GET /session/:id/tasks内のisHistoricalなど、デーモンの再起動によって中断されたものなど）も受け入れます。実行はスナップショットのスクリプト、args、およびsourceRefから再び開始され、アクションを送信したセッションに登録され、その完了を報告します。retryは同じ実行IDの下で実行のジャーナルを再開し、まだプロセスが実行されていないfailed実行に適用されます。rerunは、終了した実行から新しい実行IDを開始します。argsOmittedを持つ履歴エントリは、保持するには大きすぎるargsで起動されたため、どちらのアクションも適用されません。argsが保持される前に書き込まれたスナップショットも適用されません。これはargsOmittedもargsRecordedも含みません。実行のジャーナルはそのargsのハッシュからキー付けされるため、そのargsを履歴が特定できないものを再起動すると、何も再生されずすべてのエージェントが再ディスパッチされます。両方の拒否はworkflow_args_unavailableであり、GET /session/:id/tasksは両方をエントリ上のargsUnavailableとして報告します。これにより、クライアントは呼び出しを行うことで拒否を発見する代わりに、2つのアクションを保留できます。argsOmittedは理由としてその隣に残り、どの理由かを伝えたいクライアント向けとなります。args自体は決してワイヤー上に置かれません。

run-scriptは定義名を渡さないため、実行はスクリプト自身のexport const metaでラベル付けされます。コンパイルされたスクリプトはそれを宣言すべきですが、そうでない場合、実行はIDのみを表示します。

応答は、開始された実行の場合は{"changed": true, "status": "running", "taskId": "<runId>"}、有効になった制御アクションの場合は{"changed": true, "status": "<status>"}、何も发生しなかった場合は{"changed": false}です。セッションでWorkflowが利用不可（無効化、ベアモード、信頼できないフォルダ）、ワークスペースが信頼できない、保存されたワークフロー名が不明、実行IDが不明、または同じtaskIdの下で別の開始がすでに進行中の場合です。重複する開始のみが重複排除されます。1つのtaskIdの下での2つの同時run-script呼び出しは1つの実行を開始します。その開始が返ると、キーは解放されます。再度送信すると別の実行を開始できますが、最初の実行がまだアクティブである可能性があります。このキーは、レスポンスを失った後のリトライ冪等性を提供しません。

拒否されたパラメータは、開始された実行ではなく400（ACP経由では-32602）です。不明なaction、scriptのないrun-script、空でない文字列の{id, revision}ではないsourceRef、または構文エラーや決定性違反のために起動前に拒否されたスクリプトです。Workflow開始入力エラーはworkflow_invalid_paramsを含み、拒否メッセージを保持します。

4つの拒否は、リクエストではなく実行の保存された状態から生じます。それぞれはACP経由で-32602であり、そのerrorKindとそのdata.httpStatusを含みます。3つは409です。4番目のworkflow_not_recordedは503です。何も開始されず、同じ呼び出しを単に再試行できる可能性があるためです。retryは、実行が再び実行中であることを開始前に記録します。この記録が別のプロセスによる二重開始を防ぎますが、その記録を書き込めませんでした。

workflowToolFeatures は GET /session/:id/supported-commands で runSavedArgs と runScript を広告します。これらを備えないデーモンは、開始入力も run-script アクションも受け付けません。また nameOnly を含み、セッションのモデルが名前付きワークフローのみを実行できる場合に true となります（tools.workflowNameOnly）。モデル自身の script および scriptPath の呼び出しは拒否されますが、上記のすべてのアクション（run-script を含む）は依然として実行を開始できます。retryHistorical は、retry と rerun が履歴から復元された実行を受け入れる場合に true となります。古いデーモンはこれらに {"changed": false} で応答するため、クライアントはこれらのコントロールを、報告されている場合のみ履歴エントリに対して提供すべきです。

GET /session/:id/lsp

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