kenaz 0.3.22 → 0.3.24

package/core/dev/specs/agent-connect/history/FEATURE_REQUEST_kenaz-agent-hub_2026-09-09_v0.4-session-channel.md

@@ -1,87 +0,0 @@
-# Feature Request: Agent Connect v0.4 之後——網站與「Kenaz 開的那個 agent session」的持續對話（聊天視窗）需要 SDK 開放 session 通道
-
-日期：2026-09-09
-來源：FlowPix / GameAsset_auto（Ansuz session，接在 TASK_110「FlowPix 接上 Kenaz Agent Connect v0.4」之後）
-接續：`FEATURE_REQUEST_kenaz-agent-hub_2026-09-09_v0.4-prompt-mojibake.md`（同日缺陷報告）、`dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` §2.3/§2.4/§5（B 期已達成出口條件，C 期 SDK 尚未實作）
-Kenaz 版本觀察：kenaz-dashboard.exe **0.2.230**，`KENAZ_AGENT_HUB_DEV=1`。
-
-## 一句話
-
-FlowPix 的下一步是把「連接 Kenaz」做成網頁上的**聊天視窗**：用戶在網頁反覆對 Kenaz 開的那個 agent 下指令、看它回了什麼、看它在做什麼。v0.4 的兩個事實讓這件事只能做一半：**Web → Kenaz 只有一次性的深連結**（每按一次 = 新審批 + 新終端分頁 + 新 session，不是對既有 session 說話），**Kenaz → Web 沒有回程通道**（網站只看得到 agent 主動經網站 MCP 送出的東西）。FlowPix 會先用「agent 自己來網站 MCP 拉訊息」的信箱模式把聊天做起來（不需要 Kenaz 改任何東西，見第 2 節），但有四件事只有 Kenaz 能提供，請納入 C 期 SDK：**S1 session 識別**、**S2 持續對話的慣例由 Kenaz 人格保證**、**S3 session 輸出串流**、**S4 session 結束通知**。全部是 v0.4 的**加法**，不引回 relay，符合 Q7（互動終端分頁 + Ansuz 人格 + 網站 MCP）與 Q10（沒有中介）。
-
-## 1. 今天量到的現況（v0.4 端到端已通）
-
-- 從 `http://localhost:5173` 按一次「連接 Kenaz」→ 審批卡 → 允許 → `[AgentHub] Launched for http://localhost:5173 — agent=claude session=12b19338-23ee-4e7c-8d5b-c299dcd6e89b` → 終端分頁 → agent 呼叫 `mcp__127__kenaz_hello` → FlowPix 面板「Kenaz 已連線」。深連結、審批卡、MCP 預配、`kenaz_hello` 全部符合 PROTOCOL.md v0.4。
-- Kenaz 內部有 session id（上面 log 那個 uuid），但**網站拿不到**：`kenaz_hello` 無參數、MCP 預配只帶 `Authorization` 一個 header。網站目前只能用「每個 token = 一次連接」自己對應 session。
-- 本機 API `http://127.0.0.1:18080/api/agent-hub/` 只有 `status`、`revoke`；`sessions`、`session` 都是 404。
-- 再按一次「連接」= 再一張審批卡（origin 是 `once`）+ 再一個終端分頁 + 再一個 agent；前一個 session 沒有任何方式收到第二則訊息。
-- session 結束（用戶關分頁、CLI 崩潰）網站完全不知道，只能靠 token 閒置過期（FlowPix 設 30 分鐘）猜。
-- 深連結 `prompt=` 的中文在終端裡是亂碼（另一份報告），所以「用深連結傳指令」目前連第一則都不可靠。
-
-## 2. FlowPix 自己會做的（不依賴 Kenaz，作為基線）
-
-信箱模式：網頁把訊息 `POST` 到 FlowPix 自己的 MCP 所在的 bridge，MCP 多兩個工具——`wait_for_instruction()`（長輪詢，最多約 25 秒內回「有訊息」或「還沒有，再呼叫」）與 `reply(text)`——深連結的 `prompt=` 只放一句 ASCII 的「call wait_for_instruction in a loop and follow each instruction」，中文全部從信箱進去（走 MCP 的 JSON，繞開亂碼）。這樣聊天視窗就成立，網站也能靠長輪詢的節奏當心跳。
-
-它的弱點正好就是下面四個需求存在的理由：
-
-- **迴圈靠 agent 自律**：agent 認為「做完了」就停止呼叫工具，信箱從此沒人領；網站無從喚醒它（S2）。
-- **閒置燒 token**：agent 每 25 秒醒一次「沒有訊息」，一小時 140 多次工具呼叫（S2 的 Kenaz 側輪詢或推送可以省掉）。
-- **看不到 agent 在做什麼**：只有 `reply` 寫的摘要，終端裡的思考、工具呼叫、錯誤看不到（S3）。
-- **不知道 session 死了**：只能等閒置過期（S4）。
-- **CLI 工具審批**：Claude Code / Codex 在互動終端裡第一次呼叫網站工具會問用戶，用戶要按「永遠允許」；Kenaz 預配 MCP 時若能一併預設允許網站 MCP 的工具（審批卡已經等於用戶同意這個網站了），體驗會好很多（附帶請求 S5）。
-
-## 3. 需求
-
-### S1 讓網站認得 session（最小、無風險）
-
-Kenaz 預配網站 MCP 時，在 `headers` 多帶一個 `X-Kenaz-Session: <session uuid>`（與現有 `Authorization` 並列）。網站 MCP 每個請求都能讀到，不需要改 `kenaz_hello` 的形狀（PROTOCOL §2 fixture 維持逐字不變）。
-
-- 用途：一個 token 若被同一個 session 之外的東西使用可以拒絕；聊天視窗、transcript、結束通知都以它為鍵。
-- 建議一併在 `GET /api/agent-hub/status` 的每個 origin 下列出 `sessions:[{session_id, agent, model, cwd, started_at, alive}]`，供本機工具（FlowPix 的 bridge 在用戶機器上）查活著的 session。
-
-### S2 讓「持續對話」成為 Kenaz 人格保證的慣例，而不是網站 prompt 的祈禱
-
-PROTOCOL §2 現在只定義 `kenaz_hello`。請再定義一個**可選**慣例工具：網站 MCP 若在 `tools/list` 提供 `kenaz_wait_for_message()`（無參數；回 `{"message": string|null, "message_id": string|null}`，最長阻塞 N 秒後回 null），Kenaz 注入的 Ansuz 人格就承諾：處理完起始 `prompt`（或沒有 prompt）之後，**持續呼叫 `kenaz_wait_for_message`，每則訊息當成新的使用者訊息處理，直到工具回 `{"message":"__kenaz_end__"}` 或分頁關閉**。
-
-- 這把「agent 會不會一直聽」從網站的 prompt 工程搬到 Kenaz 人格，網站只要實作一個工具。深連結 `prompt=` 可以省略，亂碼問題也就不在關鍵路徑上。
-- 若 Kenaz 願意更進一步：由 Kenaz 側（不是 agent）代為輪詢或改成 Kenaz 提供推送——例如 Kenaz 對網站 MCP 開一條 SSE（MCP streamable HTTP 本來就有 GET 通道）收 `notifications/message`，再注入終端當使用者訊息。這能省掉閒置期的 token，但 S2 的人格慣例版本已經足夠讓聊天成立，請先做這個。
-- 審批卡：網站宣告了 `kenaz_wait_for_message` 時，卡上加一行「此網站會持續傳送指令給這個 agent」，讓用戶知道這不是一次性任務。
-
-### S3 session 輸出串流（讓聊天視窗看得到 agent 在做什麼）
-
-二擇一，或都做：
-
-- **S3a（本機、給有本機 bridge 的網站，FlowPix 現在就是）**：本機 API `GET /api/agent-hub/sessions/{id}/events`（SSE 或 WebSocket，loopback-only，與現有 `status`/`revoke` 同一個 18080 服務），事件至少含 `assistant_text`、`tool_call {name, args_preview}`、`tool_result {ok}`、`error`、`exit`。網站的本機 bridge 訂閱後轉給網頁。需要用戶同意：審批卡多一個勾選「允許此網站讀取這個 session 的輸出」，或 `always` 狀態附帶此權限。
-- **S3b（雲端網站也能用）**：Kenaz 把同一組事件以 MCP 呼叫送到網站 MCP 的慣例工具 `kenaz_session_event(event)`（網站有提供才送，帶同一個 bearer）。這是「Kenaz 自己呼叫網站 MCP」，和 S4 同一個機制。
-
-我們知道 S3 與 v0.4「Kenaz → Web 沒有回程通道」的立場相抵；請把它視為 C 期的**可選、需用戶同意**的能力，預設關閉。沒有它，聊天視窗只能顯示 agent 用 `reply` 寫的摘要，這對「看 agent 在畫布上做事」的產品需求太薄。
-
-### S4 session 結束通知
-
-Kenaz 擁有終端分頁的 PTY，程序退出或分頁被關時它是唯一知道的人。請在那一刻由 **Kenaz 本身**（不是 agent，agent 崩潰時已不存在）對網站 MCP 呼叫慣例工具 `kenaz_session_ended({reason})`（`reason`: `closed_by_user` / `agent_exited` / `error`），帶同一個 bearer；網站沒提供這個工具就略過。這樣網站可以立刻撤銷 token、把聊天視窗切成「agent 已離線」，不必猜。
-
-### S5（附帶）預設允許網站 MCP 的工具呼叫
-
-用戶在審批卡按允許時已經同意讓這個網站的 MCP 進到 agent；請在預配時同時把該 MCP 的工具設為 allowed（Claude Code 的 `permissions.allow` `mcp__<name>__*`、Codex 的對應設定），否則聊天裡每一則指令的第一個工具呼叫都會在終端再問一次，網頁端的用戶看不到那個提問，只會覺得「沒反應」。
-
-## 4. 優先順序與相依
-
-| 需求 | 對 FlowPix 的價值 | Kenaz 側工作量（我們的估計） |
-|---|---|---|
-| S1 header | 中：正確綁定 session | 小：預配 MCP 時多一個 header |
-| S2 人格慣例 | **高**：聊天視窗可靠成立、繞開亂碼 | 小：PROTOCOL §2 加一段 + 人格 prompt 加一段 + 假 MCP 加一個工具 |
-| S5 預設允許 | 高：聊天不會卡在終端的提問 | 小到中：兩個 CLI 的設定寫法 |
-| S4 結束通知 | 中：不用猜 session 死活 | 中：PTY 退出 hook + 一次 MCP 呼叫 |
-| S3 輸出串流 | 高（產品）| 大：事件模型 + 權限 + 本機 API 或推送 |
-
-建議 C 期先做 S1 + S2 + S5（都是「慣例 + 設定」層級），S4 其次，S3 獨立評估。FlowPix 會先以第 2 節的信箱模式上線，S2 落地後把迴圈指令從 prompt 移除、S1 落地後把 session 綁定改成 header。
-
-## 5. 對 SDK 套件的對應（§2.4）
-
-- `@kenaz/connect-mcp`：提供 `kenaz_wait_for_message` / `kenaz_session_ended` / `kenaz_session_event` 三個慣例工具的骨架與一個記憶體信箱，網站只要接自己的 UI。
-- `@kenaz/connect`（瀏覽器）：`<KenazConnectButton>` 之外加 `useKenazChat({session})`：送訊息、收回覆、收事件、離線狀態。
-- 假 Kenaz：模擬「呼叫 kenaz_hello → 迴圈呼叫 kenaz_wait_for_message → 對每則訊息回一個假回覆 → 呼叫 kenaz_session_ended」，網站不裝 Kenaz 也能測聊天。
-
-## 6. 怎麼看到現況（可重現）
-
-同 `FEATURE_REQUEST_kenaz-agent-hub_2026-09-09_v0.4-prompt-mojibake.md` 第「怎麼重現」節起 FlowPix；連線成功後再按一次「重新連接」，觀察：第二張審批卡、第二個終端分頁、第一個分頁的 agent 對第二則訊息毫無反應；`curl http://127.0.0.1:18080/api/agent-hub/sessions` → 404。

package/core/dev/specs/agent-connect/history/FLOWPIX_REPLY_agent-hub_2026-09-08_relay-v1-answers.md

@@ -1,68 +0,0 @@
-# FlowPix 側回覆：A／B／C 三個問題的答案（回應 KENAZ_RESPONSE … relay-v1-conformance）
-
-日期：2026-09-08
-來源：FlowPix / GameAsset_auto（Ansuz session）
-回應對象：`KENAZ_RESPONSE_agent-hub_2026-09-08_relay-v1-conformance.md`
-
-## 一句話
-
-三個問題都有答案，D1–D10 的裁定全部接受，不需要再猜。`KENAZ_AGENT_HUB_DEV=1` 已設進使用者環境變數，Kenaz 重啟後我們立刻用真實配對驗證，並把觀察到的 frame 逐則回報。
-
-## A. 合約原文（已放 Downloads）
-
-- `C:\Users\Wei\Downloads\FLOWPIX_bridge_CONTRACT.md` —— `bridge/CONTRACT.md` 全文。前半是 bridge HTTP contract v1 與「Agent hub v1」（`/mcp` 的 11 個畫布工具，K8 啟動的 CLI 會用到），後半「Relay v1」章節是這次對齊的本體。
-- `C:\Users\Wei\Downloads\FLOWPIX_bridge_agent_relay_client.py` —— 假 Kenaz 參考實作，逐訊息對照用。
-- `C:\Users\Wei\Downloads\FLOWPIX_spikes_relay_spike_relay.mjs` —— relay 參考實作，token 一次性／60 秒／綁 origin 與 `token_invalid` vs `token_already_used` 的判定都在這裡。
-
-抱歉前兩次沒附上，這次起合約每次改版都會重放到 Downloads。
-
-## B. `generate_image` 的 `payload.url` 由 relay 代理 presign（選項 2 的變體）
-
-**答案：走 relay，用同一條已配對的 WS 拿 presigned URL，Kenaz 對 `put_url` 做一次 HTTPS PUT，`result.payload.url` 回 `get_url`。** 不選 (1)，因為你們 D10 已確認 `generate_*` 完全不用 MCP，圖片上傳不該反過來把 MCP 變成必要；不選 (3)，因為產品是雲端網站，同機 URL 在正式環境不成立。
-
-新增兩則訊息（會寫進合約新的 §10，欄位定稿如下）：
-
-```json
-Kenaz -> relay: {"type": "blob.presign", "request_id": "<id>", "content_type": "image/png", "bytes": <int, optional>}
-relay -> Kenaz: {"type": "blob.presigned", "request_id": "<id>", "put_url": "<https url>", "get_url": "<https url>", "expires_s": <int>}
-              | {"type": "error", "request_id": "<id>", "error": {"code": "presign_failed", "message": "<string>"}}
-```
-
-- `request_id` 是 Kenaz 自己產生的新 id（不是 `generate_image` 那個），relay 用它配對回覆。
-- Kenaz 對 `put_url` 送 `PUT`，`Content-Type` 同 `content_type`，body 是原始 bytes；2xx 即成功。`put_url` 是 presigned URL，不帶任何 Kenaz 側憑證。
-- 之後 `result {request_id:<generate_image 的 id>, ok:true, payload:{url:<get_url>, width, height, provider, elapsed_ms, meta}}`。
-- 這正是 spike 裡假 Kenaz 已在做的事（`agent_relay_client.py` 的 `_upload_to_blobstore`：POST `/presign` → PUT `put_url` → 回 `get_url`），只是把「presign 端點在哪」從命令列參數改成走 relay 訊息，Kenaz 不用多知道任何 URL，也不用多一組憑證。
-- 一則 `generate_image` 可以呼叫多次 `blob.presign`（多張輸出時），relay 不限制次數。
-- `reference_images[]` 方向相反（網站→Kenaz 給 URL），Kenaz 直接 GET 即可，這部分不變。
-
-relay 這邊我們會實作（`relay.mjs` 代理到 blobstore；正式環境是 R2/GCS 的 presigned URL）。在你們落地前，D7 image 分支先回本機路徑我們可以接受，網站端會顯示「等待 Kenaz 上傳」。
-
-## C. `agent.launched` / `agent.unavailable` 欄位：接受
-
-- `{type:"agent.launched", request_id, agent:"claude"|"codex", mode:"interactive"|"headless", session_id?:string}` —— 接受，`session_id` 取代 §8 的 `pid`。
-- `{type:"agent.unavailable", request_id, agent, reason}` —— 接受，含改成點分隔的型別名（原 `agent_unavailable` 廢止）。
-- `agent.launch` 請求形狀 `{request_id, mode, agent?, prompt, mcp?, cwd?}` 接受，深連結只帶 `agent=` 時配對後自動起一次 interactive CLI 的體驗也接受。
-
-合約 §8 會依此重寫（由 FlowPix 改，改完重放 Downloads）。
-
-## 其餘裁定：全部接受
-
-| # | 我們的回覆 |
-|---|---|
-| D1 | 用 `KENAZ_AGENT_HUB_DEV`，**不需要**同時認第二個名字，我們沒有腳本寫死 `ALLOW_INSECURE_LOOPBACK`。`[::1]` 補上即可。 |
-| D3 | 接受，我們永遠只送 `pair.denied`。 |
-| D4 | 接受：頂層 `codex_logged_in` + `rate_limits:null`；`agents` / `dispatch` 我們忽略；`request_id` 為 uuid 我們忽略。 |
-| D5／D6 | 接受，含 `input_url` alias 與 `model` 的 best-effort 語意。 |
-| D7 | 接受，image 的 URL 見 B。 |
-| D8 | 接受：`not_logged_in` 必做；`usage_limit_exceeded` best-effort、`resetsAt` 可為 `null`；新增 `paused` 我們會顯示「Kenaz 已暫停」。錯誤碼全集合會寫進合約 §7。 |
-| D9／D10 | 見 C；`mcp=` 選填確認。 |
-
-## 我們這邊還需要你們確認一件事（不卡合約，卡我們的實作）
-
-**D. K8 啟動 CLI 時，Kenaz 對網站 MCP 的 `Authorization: Bearer <?>` 放的是什麼？** 我們的理解是 `pair.ok` 的 `session_credential`（M2 測試裡 `mcpServers.flowpix.headers.Authorization = "Bearer cred-abc-123"` 的 cred）。若是，FlowPix 的 `/mcp` 會改成接受 relay 發出的 session credential（目前只認本機單一 token `GAMEASSET_BRIDGE_AGENT_TOKEN`）。另外請確認 `agent.launch.mcp` 與深連結 `mcp=` 的值都是**單一 URL 字串**（Kenaz 自己組成 `{mcpServers:{flowpix:{type:"http",url,headers}}}`），而不是要網站送整份 config JSON。
-
-## 接下來（FlowPix 側）
-
-1. Kenaz 重啟帶 `KENAZ_AGENT_HUB_DEV=1` 後，用 9/8 報告的重現步驟實際配對，回報 relay frame log 裡 Kenaz 送出的每一則（`pair.begin` → `agent.status` → …）。
-2. 更新 `bridge/CONTRACT.md`：§2 加選填 `mcp=`、§4 註明可忽略的額外欄位、§7 錯誤碼全集合、§8 重寫為請求語意 + 兩則公告、新 §10 `blob.presign`；三方實作（relay.mjs / agent_relay_client.py / backend RelaySiteClient）與 `test_contract_consistency.py` 同步。改完重放 Downloads。
-3. 你們的驗收 1–4 我們在真實 Kenaz 上跑，結果附 frame log 回報。