# Daemon ACP-over-HTTP → 公式 ACP Streamable HTTP トランスポート
 
> 対象: `daemon_mode_b_main` ブランチ。ブランチ: `feat/daemon-acp-http-streamable`。
> 著者: arnoo.gao。日付: 2026-05-24。ステータス: **Design v1 → 実装**。
> リポジトリのワークフローに従い、設計ファースト: このドキュメントは実装 PR と同時または先行して作成され、ワイヤー契約をレビュー可能にします。
 
---
 
## 0. TL;DR
 
現在、デーモン（`qwen serve`）は Web/SDK クライアントに対して **独自の REST + SSE** 方言で通信し、生成された `qwen --acp` 子プロセスに対しては **本当の ACP JSON-RPC over stdio** で通信しています。この提案では、**公式の ACP Streamable HTTP トランスポート**（RFD #721）を単一の `/acp` エンドポイントで実装する **2 番目のノースバウンドトランスポート** を追加します。これにより、ACP ネイティブクライアント（Zed、Goose、将来の SDK）は、qwen 固有の REST 知識を必要とせず、標準プロトコル経由で直接デーモンを駆動できます。
 
**決定: デュアルトランスポート（追加的）。** 新しい `/acp` エンドポイントは既存の REST サーフェスと並行してマウントされ、内部で同じ `HttpAcpBridge` + `EventBus` を再利用します。REST API は**削除しません**。根拠は §6。
 
**決定: 拡張名前空間 = `_qwen/…`**（シングルアンダースコアプレフィックス、ACP 仕様でカスタムメソッド用に予約された形式）。標準の ACP メソッドがないデーモン機能（モデル切り替え、ワークスペースイントロスペクション、ハートビート、マルチクライアント権限ポリシー、SSE バックプレッシャーチューニング）に使用します。根拠は §5。
 
この PR には、完全でローカル実行可能なリファレンス実装（`packages/cli/src/serve/acp-http/`）と検証ハーネス（`scripts/acp-http-smoke.mjs`）が含まれています。
 
---
 
## 1. 背景 — 今日の「ACP over HTTP」の意味
 
3 つの層（コミット `0c0430939` で確認）:
 

### 1.1 ノースバウンド（クライアント ↔ デーモン）— 現在は独自

- Express 5 アプリ (`packages/cli/src/serve/server.ts`、約 30 ルート)
- 個別の REST 動詞、**JSON-RPC ではない**:
  - `POST /session` (作成)、`POST /session/:id/prompt`、`POST /session/:id/cancel`、
    `POST /session/:id/load|resume`、`POST /session/:id/model`、
    `POST /session/:id/permission/:requestId`、`POST /session/:id/heartbeat`、
    `DELETE /session/:id`、さらに `/workspace/*`、`/capabilities`、`/health`。
- サーバー→クライアントストリーミング: `GET /session/:id/events` → `text/event-stream`。
  - フレーム: `id: <n>\nevent: <type>\ndata: <json>\n\n` (`server.ts:formatSseFrame`、約 2626行)。
  - セッションごとの**単調増加 `id`** + `Last-Event-ID` 再開、リングバッファ `EventBus` (`acp-bridge/src/eventBus.ts`) でバックアップ。
  - イベント `type`: `session_update`、`client_evicted`、`slow_client_warning`、
    `state_resync_required`、`stream_error`、…
- 認証: `Authorization: Bearer <token>` (`serve/auth.ts`)、CORS 拒否 + ホスト許可リスト。
- バックプレッシャー: 接続ごとのシリアル化された書き込みチェーン + 15 秒のハートビートコメント。

### 1.2 サウスバウンド（デーモン ↔ 子プロセス）— すでに ACP

- `acp-bridge/src/spawnChannel.ts` が `qwen --acp` を起動し、stdin/stdout を `@agentclientprotocol/sdk` (`^0.14.1`) の `ndJsonStream` でラップ。
- `acp-bridge/src/bridge.ts:729` `new ClientSideConnection(() => client, channel.stream)` — デーモンは ACP **クライアント**、子プロセスは ACP **エージェント**。
- この区間ではすでに拡張メソッドが使用中: `unstable_setSessionModel`、`unstable_resumeSession`、`unstable_listSessions` (`acp-integration/acpAgent.ts`)。

### 1.3 なぜノースバウンドを移行するのか

- すべてのクライアント（webui、TS SDK、Java SDK、Python SDK、VSCode コンパニオン）が独自の REST マッピングを再実装しています。ACP 標準エンドポイントを使用すれば、ACP ネイティブエディタは qwen 固有のグルーコードなしで接続できます。
- デーモンのリモートサーフェスを、内部ですでに話しているプロトコルと整合させます。

---

## 2. 目標: ACP Streamable HTTP (RFD #721)

マージ済み **Draft** RFD (`agentclientprotocol/agent-client-protocol#721`、2026-04-22 マージ)。
まだ規範的ではなく、どの SDK にも含まれていません。RFD のワイヤーデザインに従って実装します。

### 2.1 エンドポイントと動詞（単一の `/acp`）

| 動詞          | 動作                                                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /acp`   | JSON-RPC を送信。`initialize` → **`200`** + JSON 本文（機能）で応答し、`Acp-Connection-Id` を設定。その他のリクエスト/通知 → **`202 Accepted`**、空の本文; 応答（ある場合）は、対応する長期間存続する SSE ストリームで配信。 |
| `GET /acp`    | 長期間存続する **SSE** ストリームを開く。（`Upgrade: websocket` → WebSocket; **延期**、§7 参照。）                                                                                                                                                     |
| `DELETE /acp` | コネクションを終了 → `202`。                                                                                                                                                                                                               |

### 2.2 2 層の長期間存続ストリーム

- **コネクションスコープのストリーム**: `Acp-Connection-Id` ヘッダーを持つ `GET /acp`、セッションヘッダーなし。コネクションレベルの応答（`session/new`、`session/load`、`authenticate`）とコネクションレベルの通知を運びます。
- **セッションスコープのストリーム**: `Acp-Connection-Id` **および** `Acp-Session-Id` を持つ `GET /acp`。`session/update` 通知、**エージェント→クライアントリクエスト**（`session/request_permission`、`fs/read_text_file`、…）、およびセッション POST への応答（`session/prompt`、`session/cancel`）を運びます。

### 2.3 識別子（3 層）

- `Acp-Connection-Id`（HTTP ヘッダー）— トランスポートバインディング、`initialize` 時に生成。
- `Acp-Session-Id`（HTTP ヘッダー）— セッションスコープの GET およびセッション POST で必須。
- `sessionId`（JSON-RPC パラメータ）— メソッドパラメータ内（ヘッダーと一致する必要がある）。

### 2.4 MCP StreamableHTTP との相違点

ACP は **長期間存続する** ストリーム（リクエストごとの SSE ではない）、**2 つ** の ID ヘッダー（コネクション vs セッション）、非初期化リクエストには `202`、HTTP/2 必須、WebSocket 必須クライアントを使用します。単一エンドポイント + POST/GET-SSE + セッションヘッダーの骨格は借用しますが、長期間存続するデュアル ID モデルに適合させます。`@modelcontextprotocol/sdk` の `StreamableHTTPServerTransport` は**再利用しません**（そのリクエストごとのストリームモデルと単一の `Mcp-Session-Id` は適合しません）。

### 2.5 標準メソッド（現在のスキーマから確認）

- クライアント→エージェントリクエスト: `initialize`、`authenticate`、`session/new`、`session/load`、`session/prompt`、`session/resume`、`session/close`、`session/list`、`session/set_mode`、`session/set_config_option`、`logout`。
- クライアント→エージェント通知: `session/cancel`。
- エージェント→クライアントリクエスト: `fs/read_text_file`、`fs/write_text_file`、`session/request_permission`、`terminal/create|output|wait_for_exit|kill|release`。
- エージェント→クライアント通知: `session/update`。

---

## 3. 新しいトランスポートのアーキテクチャ

デーモンはノースバウンドで HTTP 越しの **ACP エージェントサーフェス** を提示しつつ、サウスバウンドの子プロセスに対しては ACP **クライアント** であり続けなければなりません。したがって、`/acp` 層は HTTP トランスポートを終端し、既存の `HttpAcpBridge` にブリッジする **JSON-RPC ルーター** です。

        POST /acp (JSON-RPC リクエスト/応答/通知)

### 3.1 新しいモジュール構成 (`packages/cli/src/serve/acp-http/`)

| ファイル                    | 責任                                                                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index.ts`               | `mountAcpHttp(app, bridge, opts)` — 既存の Express アプリに `/acp` ルートを登録。                                                                                                    |
| `connection-registry.ts` | `Acp-Connection-Id` → `AcpConnection`（コネクション SSE ライター、`Map<sessionId, SessionStream>`、JSON-RPC id による保留中のエージェント→クライアントリクエスト、単調増加 id アロケーター）。TTL + DELETE クリーンアップ。 |
| `json-rpc.ts`            | JSON-RPC 2.0 の解析/検証/シリアライズヘルパー; エラーコード（`-32600` など）; `_qwen/` 名前空間ガード。                                                                                       |
| `dispatch.ts`            | 受信 JSON-RPC メソッドを `HttpAcpBridge` 呼び出しにマッピング。`BridgeEvent` を送信 JSON-RPC フレームにマッピング。変換テーブル（§4）。                                                          |
| `sse-stream.ts`          | 長期間存続する SSE ライター（`server.ts` のバックプレッシャー/ハートビートパターンを再利用）。REST `/events` とは異なる（フレーミング: 完全な JSON-RPC オブジェクト、qwen イベントエンベロープではない）。      |

`bridge.ts` / `eventBus.ts` への変更はありません（追加的なコンシューマのみ）。

### 3.2 コネクションとセッションのライフサイクル

1. `POST /acp {initialize}` → `connectionId` を生成、`AcpConnection` を作成、`200` で応答 `{protocolVersion, agentCapabilities, _meta:{qwen:{…}}}` + `Acp-Connection-Id` ヘッダー。
2. クライアントが `Acp-Connection-Id` を付けて `GET /acp`（コネクションスコープ）を開く。
3. `POST /acp {session/new}` → `202`; デーモンが `bridge.createSession(...)` を呼び出し; JSON-RPC 応答（`sessionId` を含む）を**コネクション**ストリームにプッシュ。
4. クライアントが `Acp-Connection-Id` + `Acp-Session-Id` を付けて `GET /acp`（セッションスコープ）を開く; デーモンが `bridge.subscribeEvents(sessionId)` を呼び出し、変換されたフレームをパイプ。
5. `POST /acp {session/prompt}` → `202`; `bridge.sendPrompt(...)`; `session/update` 通知がセッションストリーム上でライブ配信; 最終的なプロンプト **応答**（`{id, result:{stopReason}}`）は決定時にセッションストリームにプッシュ。
6. エージェント→クライアントリクエスト（例: `session/request_permission`）は、デーモンが割り当てた id を持つ JSON-RPC **リクエスト**としてセッションストリームに出力; クライアントは `POST /acp {id, result}` で応答; `dispatch` が bridge の権限 API を通じて解決。
7. `DELETE /acp`（またはコネクションストリームクローズ + TTL）によりセッション/サブスクリプションを解体。

---

## 4. 変換テーブル（bridge ⇄ ACP/HTTP）

### 4.1 インバウンド（クライアント POST → bridge）

| ACP メソッド                                | Bridge 呼び出し                                       | 応答のルーティング先                 |
| ------------------------------------------- | ----------------------------------------------------- | -------------------------------------- | ----------------- |
| `initialize`                                | （なし; 機能は `capabilities.ts` から）               | インライン `200`                           |
| `authenticate`                              | 既存の認証プロバイダー (`serve/auth/*`)               | コネクションストリーム                      |
| `session/new`                               | `bridge.createSession`                                | コネクションストリーム                      |
| `session/load` / `session/resume`           | `bridge.restoreSession('load'                         | 'resume')`                             | コネクションストリーム |
| `session/prompt`                            | `bridge.sendPrompt`                                   | セッションストリーム（決定まで延期） |
| `session/cancel` (通知)                    | `bridge.cancel`                                       | —                                      |
| `session/list`                              | `bridge.listSessions` (`unstable_listSessions`)       | コネクションストリーム                      |
| `session/set_mode`                          | 承認モードルートロジック                             | セッションストリーム                         |
| JSON-RPC **応答**（エージェント→クライアントリクエストに対し） | 保留中の解決（`§4.3`）                              | —                                      |
| `_qwen/session/set_model`                   | `bridge.setSessionModel` (`unstable_setSessionModel`) | セッションストリーム                         |
| `_qwen/workspace/list` など                 | ワークスペースイントロスペクションルート             | コネクションストリーム                      |
| `_qwen/session/heartbeat`                   | `bridge.heartbeat`                                    | コネクションストリーム                      |

### 4.2 アウトバウンド（BridgeEvent → セッションストリーム上の JSON-RPC）

| BridgeEvent.type                                                   | 出力内容                                                          |
| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `session_update`                                                   | `{method:"session/update", params:<data>}` 通知             |
| 権限リクエスト                                                 | `{id:<n>, method:"session/request_permission", params}` リクエスト     |
| `client_evicted` / `slow_client_warning` / `state_resync_required` | `{method:"_qwen/notify", params:{kind,…}}` 通知             |
| `stream_error`                                                     | アクティブなプロンプト id の JSON-RPC エラー応答（または `_qwen/notify`） |
| プロンプト決定                                              | `{id:<promptId>, result:{stopReason}}`                              |

### 4.3 保留中のエージェント→クライアントリクエスト

`AcpConnection` は `Map<jsonRpcId, {sessionId, kind, bridgeRequestId, resolve}>` を保持します。クライアントが JSON-RPC 応答オブジェクトを POST すると、`dispatch` は `id` を照合し、bridge の解決パス（例: 権限 `POST /session/:id/permission/:requestId` の内部相当）を呼び出します。

> **v1 ステータス:** `session/request_permission` エージェント→クライアントラウンドトリップのみ実装されています。`fs/*` および `terminal/*` のエージェント→クライアント転送は**延期**されています（§7）— デーモンは `/acp` でまだ `fs`/`terminal` クライアント能力ネゴシエーションを通知していないため、ACP クライアントは v1 でこのトランスポート上でファイルシステム/ターミナルセマンティクスを想定すべきではありません。意図する最終状態（`fs/*` をクライアントに転送; クライアントに `fs` 能力がない場合はデーモンのワークスペース FS にフォールバック）は、§7 で説明する後続作業です。

---

## 5. 拡張戦略（要件 #2）

ACP は `_` で始まるメソッドをすべてカスタム拡張用に予約し、すべてのタイプに `_meta` を提供します。コードベースのサウスバウンド区間はすでに `unstable_*` メソッド名を使用しています。

**ノースバウンドの選択:** ベンダー名前空間の **`_qwen/<area>/<verb>`** メソッド名（仕様準拠の `_` プレフィックス）。機能は `initialize` 時に `agentCapabilities._meta.qwen` の下で通知されるため、クライアントは使用前に機能検出できます。

| ニーズ                                                  | 標準の ACP メソッドは存在するか? | 拡張                                               |
| ----------------------------------------------------- | ----------------------- | ------------------------------------------------------- |
| モデル切り替え                                          | いいえ                     | `_qwen/session/set_model`                               |
| ワークスペース MCP/スキル/プロバイダー/環境イントロスペクション      | いいえ                     | `_qwen/workspace/list`、`_qwen/workspace/<area>`        |
| ハートビート / 最終確認時刻                                 | いいえ                     | `_qwen/session/heartbeat`                               |
| マルチクライアント権限ポリシー（合議制/指定） | 部分的                 | `session/request_permission` + `_meta.qwen.policy`      |
| SSE バックプレッシャーチューニング (`maxQueued`)                 | いいえ                     | セッション GET の `Acp-Qwen-Max-Queued` ヘッダー             |
| 再開カーソル（リング `Last-Event-ID`)                  | RFD フェーズ 4             | `Last-Event-ID` ヘッダー + フレームの `_meta.qwen.eventId` |

標準メソッドは**決して名前変更されません**。拡張は厳密に追加的であり、無視可能です。

---

## 6. デュアルトランスポート vs. 置換（要件 #4）

**決定: デュアルトランスポート（追加的）。**

- 公式トランスポートは **Draft** RFD であり、規範的ではなく、どの SDK にも存在しません。強制的に置き換えると、未承認の設計に結合され、webui + 3 SDK + VSCode コンパニオンが同時に壊れます。
- REST サーフェスには、まだ明確な ACP マッピングがない機能（ワークスペースイントロスペクション、マルチクライアント権限調停、リングバッファ再開、機能レジストリ）が含まれています。これらは `/acp` では `_qwen/*` 拡張に格下げされますが、REST サーフェスは RFD が承認されるまで権威あるものとして残ります。
- 両方のトランスポートは **1 つ**の `HttpAcpBridge` + `EventBus` インスタンスを共有するため、状態の重複はありません — `/acp` と `/session/*` は同じライブセッションを同時に駆動することも可能です（マルチクライアントはすでに bridge でサポートされています）。
- トグル（v1、出荷時）: デフォルトで有効; **`QWEN_SERVE_ACP_HTTP=0`** でマウントを無効化。`--no-acp-http` CLI フラグと `/capabilities` の `acp_http` タグによるクライアント機能検出は **後続作業に延期**（v1 には含まれません）— それまでは、クライアントは `POST /acp {initialize}` をプローブしてトランスポートを検出します。

移行パス: RFD が承認され SDK が出荷されたら、REST ルートは `/acp` 上の薄い互換性シムとして再構成できます（別の後続 PR）。

---

## 7. 実装 PR の範囲

**範囲内（ローカルで実行可能かつ検証済み）:**

- `POST /acp` ディスパッチ（`initialize`、`session/new`、`session/prompt`、`session/cancel`、`session/load`、JSON-RPC 応答処理）
- コネクションスコープ + セッションスコープの `GET /acp` SSE ストリーム（JSON-RPC フレーミング）
- `session/update` ストリーミング + 最終プロンプト応答の相関
- `session/request_permission` エージェント→クライアントラウンドトリップ
- `_qwen/session/set_model` 拡張（要件 #2 の実例）
- Bearer 認証 + ホスト許可リストの再利用（REST と同じミドルウェア）
- 単体テスト (`acp-http/*.test.ts`) + 実際のデーモンを駆動するブラックボックス Smoke スクリプト

**延期（文書化のみ、今は実装しない）:**

- WebSocket アップグレードパス（RFD 必須のクライアント機能; ローカル検証には SSE で十分）
- HTTP/2 多重化（HTTP/1.1 で実行; POST と長期間存続 GET は別々のソケットを使用。これは CLI/Node クライアントおよび ≤6 接続のブラウザで動作）。相違点として文書化。
- 完全な `fs/*` + `terminal/*` エージェント→クライアント転送（権限パスでメカニズムを立証; 残りは機械的な後続作業）
- リングバッファとのパリティを持った SSE 再開可能な耐久性の強化（RFD フェーズ 4）

✓ initialize: connectionId=… protocolVersion=1
✓ session/new: sessionId=…
→ prompt: "Reply with the single word: pong"
pong
✓ prompt complete: 10 session/update frames, stopReason=end_turn
✓ DELETE /acp — connection closed
ALL CHECKS PASSED ✅