kenaz 0.0.0-stage → 0.3.2

package/core/dev/specs/agent-connect/examples/minimal-site/test/smoke.test.mjs

@@ -0,0 +1,263 @@
+// Smoke test for the minimal example site (TASK_1940).
+// Run: node --test dev/specs/agent-connect/examples/minimal-site/test/smoke.test.mjs
+//
+// Proves the MCP endpoint's bearer gate actually works end-to-end (this is
+// the "control group" AC in the task card: "範例網站的 MCP 對錯誤 bearer 回
+// 401") — starts a real HTTP server on an OS-assigned port, makes real
+// requests, and closes the server when done. No mocking of server.js
+// itself: this exercises the exact code path a real browser click would.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from '../server.js';
+import { resolveInstallRedirect, buildInstallRedirectUrl } from '../public/install-redirect.js';
+
+test('POST /api/connect mints a token and returns a well-formed kenaz://connect deep link', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const res = await fetch(`${demo.baseUrl}/api/connect`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ prompt: 'hello' }),
+  });
+  assert.equal(res.status, 200);
+  const { deepLink, token } = await res.json();
+  assert.ok(token, 'expected a token');
+
+  const parsed = new URL(deepLink);
+  assert.equal(parsed.protocol, 'kenaz:');
+  assert.equal(parsed.hostname, 'connect');
+  assert.equal(parsed.searchParams.get('site'), demo.baseUrl);
+  assert.equal(parsed.searchParams.get('mcp'), `${demo.baseUrl}/mcp`);
+  assert.equal(parsed.searchParams.get('token'), token);
+  assert.equal(parsed.searchParams.get('prompt'), 'hello');
+});
+
+test('POST /mcp with no bearer, or the wrong bearer, is rejected with 401', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const rpc = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'kenaz_hello', arguments: {} } };
+
+  const noAuth = await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(rpc),
+  });
+  assert.equal(noAuth.status, 401);
+
+  const wrongAuth = await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: 'Bearer not-a-real-token' },
+    body: JSON.stringify(rpc),
+  });
+  assert.equal(wrongAuth.status, 401);
+});
+
+test('control group: a legitimate token in the same run is still accepted (401 is not a global outage)', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const connectRes = await fetch(`${demo.baseUrl}/api/connect`, { method: 'POST' });
+  const { token } = await connectRes.json();
+
+  const res = await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'kenaz_hello', arguments: {} } }),
+  });
+  assert.equal(res.status, 200);
+  const body = await res.json();
+  const payload = JSON.parse(body.result.content[0].text);
+  assert.deepEqual(payload, { ok: true });
+});
+
+test('kenaz_hello call is reflected in /api/status/:token', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const connectRes = await fetch(`${demo.baseUrl}/api/connect`, { method: 'POST' });
+  const { token } = await connectRes.json();
+
+  const before = await fetch(`${demo.baseUrl}/api/status/${token}`);
+  assert.equal((await before.json()).connected, false);
+
+  await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'kenaz_hello', arguments: {} } }),
+  });
+
+  const after = await fetch(`${demo.baseUrl}/api/status/${token}`);
+  const afterBody = await after.json();
+  assert.equal(afterBody.connected, true);
+  assert.ok(afterBody.calledAt);
+});
+
+// ── TASK_1948: kenaz_wait_for_message mailbox ──────────────────────────
+
+test('POST /message delivers into the mailbox and kenaz_wait_for_message returns it', async (t) => {
+  const demo = createServer({ port: 0, waitTimeoutMs: 5_000 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const connectRes = await fetch(`${demo.baseUrl}/api/connect`, { method: 'POST' });
+  const { token } = await connectRes.json();
+
+  const deliverRes = await fetch(`${demo.baseUrl}/message`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token, message: 'summarize the canvas' }),
+  });
+  assert.equal(deliverRes.status, 200);
+  const { message_id: deliveredId } = await deliverRes.json();
+  assert.ok(deliveredId);
+
+  const waitRes = await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+    body: JSON.stringify({
+      jsonrpc: '2.0', id: 2, method: 'tools/call',
+      params: { name: 'kenaz_wait_for_message', arguments: {} },
+    }),
+  });
+  assert.equal(waitRes.status, 200);
+  const body = await waitRes.json();
+  const payload = JSON.parse(body.result.content[0].text);
+  assert.equal(payload.message, 'summarize the canvas');
+  assert.equal(payload.message_id, deliveredId);
+});
+
+test('kenaz_wait_for_message returns null message/message_id when nothing was delivered, after the long-poll window', async (t) => {
+  const demo = createServer({ port: 0, waitTimeoutMs: 150 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const connectRes = await fetch(`${demo.baseUrl}/api/connect`, { method: 'POST' });
+  const { token } = await connectRes.json();
+
+  const start = Date.now();
+  const waitRes = await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+    body: JSON.stringify({
+      jsonrpc: '2.0', id: 2, method: 'tools/call',
+      params: { name: 'kenaz_wait_for_message', arguments: {} },
+    }),
+  });
+  const elapsedMs = Date.now() - start;
+  const body = await waitRes.json();
+  const payload = JSON.parse(body.result.content[0].text);
+  assert.equal(payload.message, null);
+  assert.equal(payload.message_id, null);
+  assert.ok(elapsedMs >= 140, `expected the call to actually block for ~the waitTimeoutMs window, took ${elapsedMs}ms`);
+});
+
+/// Control group: a token that was never minted (or already expired) must
+/// be rejected the same way an unknown token is rejected for /mcp — proves
+/// /message isn't a free-for-all message drop for any string.
+test('control group: POST /message with an unknown token is rejected with 404', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const res = await fetch(`${demo.baseUrl}/message`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token: 'not-a-real-token', message: 'hi' }),
+  });
+  assert.equal(res.status, 404);
+});
+
+// ── TASK_1950: "not installed" redirect (SDK_GUIDE.md §10) ─────────────
+// Uses a short (200ms) timeout rather than the real 8s default so the test
+// runs fast — the logic under test (resolveInstallRedirect /
+// buildInstallRedirectUrl) is pure and timeout-value-agnostic.
+
+test('resolveInstallRedirect: no kenaz_hello within the timeout redirects to the install page carrying return=<original deep link>', async () => {
+  const deepLink = 'kenaz://connect?site=https%3A%2F%2Fx.example&mcp=https%3A%2F%2Fx.example%2Fmcp&token=abc123';
+  const installUrl = 'https://kenaz-install.example/placeholder';
+  const timeoutMs = 200;
+  const startedAt = Date.now();
+
+  // Before the timeout elapses: no redirect yet.
+  const early = resolveInstallRedirect({ connected: false, startedAt, timeoutMs, installUrl, deepLink });
+  assert.equal(early, null, 'must not redirect before the timeout elapses');
+
+  await new Promise((resolve) => setTimeout(resolve, timeoutMs + 20));
+
+  const late = resolveInstallRedirect({ connected: false, startedAt, timeoutMs, installUrl, deepLink });
+  assert.ok(late, 'expected a redirect URL once the timeout elapses without kenaz_hello');
+  const parsed = new URL(late);
+  assert.equal(parsed.origin + parsed.pathname, installUrl);
+  assert.equal(parsed.searchParams.get('return'), deepLink, 'return= must round-trip the exact original deep link');
+});
+
+/// Control group (feedback_probe_needs_control_group): a connected caller
+/// must never be redirected, even long past the timeout — proves the
+/// timeout check isn't the only thing gating the redirect.
+test('control group: resolveInstallRedirect never redirects once connected=true, even past the timeout', () => {
+  const deepLink = 'kenaz://connect?site=https%3A%2F%2Fx.example&mcp=https%3A%2F%2Fx.example%2Fmcp&token=abc123';
+  const installUrl = 'https://kenaz-install.example/placeholder';
+  const startedAt = Date.now() - 10_000; // already well past any short timeout
+
+  const result = resolveInstallRedirect({ connected: true, startedAt, timeoutMs: 200, installUrl, deepLink });
+  assert.equal(result, null);
+});
+
+test('buildInstallRedirectUrl encodes the deep link into return= (round-trips through URLSearchParams)', () => {
+  const deepLink = 'kenaz://connect?site=https%3A%2F%2Fx.example&token=a+b&prompt=hi%20there';
+  const url = buildInstallRedirectUrl('https://kenaz-install.example/placeholder', deepLink);
+  const parsed = new URL(url);
+  assert.equal(parsed.searchParams.get('return'), deepLink);
+});
+
+test('GET / injects the configured install URL + timeout into the connect button data-* attributes', async (t) => {
+  const demo = createServer({ port: 0, installUrl: 'https://custom-install.example/x', installTimeoutMs: 4242 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const res = await fetch(demo.baseUrl);
+  const html = await res.text();
+  assert.ok(html.includes('data-install-url="https://custom-install.example/x"'));
+  assert.ok(html.includes('data-not-installed-timeout-ms="4242"'));
+  assert.ok(!html.includes('__KENAZ_INSTALL_URL__'), 'placeholder must be fully substituted');
+});
+
+test('GET /install-redirect.js serves the shared pure-function module as JS', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const res = await fetch(`${demo.baseUrl}/install-redirect.js`);
+  assert.equal(res.status, 200);
+  assert.match(res.headers.get('content-type'), /javascript/);
+  const body = await res.text();
+  assert.ok(body.includes('export function resolveInstallRedirect'));
+});
+
+test('the echo demo tool round-trips its argument (proves tools other than kenaz_hello also work)', async (t) => {
+  const demo = createServer({ port: 0 });
+  await demo.listen();
+  t.after(() => demo.close());
+
+  const connectRes = await fetch(`${demo.baseUrl}/api/connect`, { method: 'POST' });
+  const { token } = await connectRes.json();
+
+  const res = await fetch(`${demo.baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+    body: JSON.stringify({
+      jsonrpc: '2.0', id: 2, method: 'tools/call',
+      params: { name: 'echo', arguments: { text: 'canvas state' } },
+    }),
+  });
+  const body = await res.json();
+  const payload = JSON.parse(body.result.content[0].text);
+  assert.deepEqual(payload, { echo: 'canvas state' });
+});

package/core/dev/specs/agent-connect/history/DEFECT_REPORT_kenaz-agent-hub_2026-09-09_v0.4-empty-prompt-no-first-turn.md

@@ -0,0 +1,77 @@
+# Defect Report: 0.2.231 深連結沒帶 `prompt=` 時，claude 分支以空字串 `''` 當第一則訊息啟動 → 互動式 Claude Code 沒有第一個 turn，`kenaz_hello` / `kenaz_wait_for_message` 迴圈永遠不會開始
+
+日期：2026-09-09
+來源：FlowPix / GameAsset_auto（Ansuz session，TASK_112 R8「對齊上游 0.2.231」的真實 Kenaz 驗收）
+對應回覆：`KENAZ_RESPONSE_agent-hub_2026-09-09_session-channel.md`（S2 段落：「處理完 `prompt`（沒有 prompt 就直接）→ 反覆呼叫 `kenaz_wait_for_message`」）、`PROTOCOL.md` §2 第 5 點（「`prompt` 為空則直接進入」）
+Kenaz 版本觀察：kenaz-dashboard.exe **0.2.231**（`D:\Users\Wei\AppData\Local\BLOCK ACTION\kenaz-dashboard.exe`，2026-09-09 06:45 啟動）；agent=claude，Claude Code v2.1.259。
+
+## 一句話
+
+S1 header、S5 `--allowedTools`、`.ps1` BOM 修正在 0.2.231 都驗證有效（見「先講好消息」）。但 S2 的前提「網站可以省略 `prompt=`，人格會直接進入迴圈」在 claude 分支**不成立**：沒有 `prompt=` 時，Kenaz 產生的啟動腳本把空字串 `''` 當位置參數傳給 `claude`，Claude Code 以互動模式開啟、停在空的輸入框等使用者打字，**沒有任何一個 turn 發生**，system prompt 裡的「先呼叫 `kenaz_hello`、再反覆呼叫 `kenaz_wait_for_message`」也就永遠不會被執行。FlowPix 端可以自救（送一句固定 ASCII 開場 prompt 當 turn 觸發器，見第 3 節），但這與 S2「網站不需要 prompt 工程」的設計意圖相違，請 Kenaz 側在 `prompt` 為空時自行補一個開場訊息。
+
+## 先講好消息：0.2.231 的其他部分都通了
+
+同一次啟動（2026-09-09 07:59 本機時間，`[AgentHub] Launched for http://localhost:5173 — agent=claude session=0e76bd42-…`）觀察到：
+
+- **亂碼修正**：`%USERPROFILE%\.kenaz\agent_hub\mcp\<id>-<uuid>.ps1` 前三個位元組是 `EF BB BF`（BOM）。前一版留下的舊 `.ps1` 是 `24 45 72`（無 BOM）。與 `KENAZ_RESPONSE_…_prompt-mojibake-fixed.md` 的 D1 一致。
+- **S1**：預配的 MCP JSON `headers` 是 `{"Authorization": "Bearer …", "X-Kenaz-Session": "137c11f5-eef5-4f56-b204-6ae4a3af8fa7"}`；`GET /api/agent-hub/status` 的 origin 底下有 `sessions: [{session_id: "137c11f5-…", pty_session_id: "0e76bd42-…", agent: "claude", model: "claude-sonnet-5", cwd: "D:\\Projects\\Ashfall", started_at, alive: true}]`。與 PROTOCOL §2 第 1b 點及 fixture `mcp.config_with_session_header` 一致。FlowPix bridge 已改成把這個 header 記到 token 上（`GET /kenaz/connect/{token}/status` 多回 `kenaz_session_id`）。
+- **S5**：啟動命令列含 `--allowedTools 'mcp__127__*'`。
+- **人格**：`-persona.txt` 第 133–135 行有 `kenaz_hello` 與 `kenaz_wait_for_message` 的迴圈約定，措辭與 PROTOCOL §2 第 5 點一致。
+
+所以 0.2.231 的 S1/S2 人格文字/S5/BOM 四項都到位。以下只有一個問題。
+
+## 問題：`prompt` 為空 → `claude … ''` → 沒有第一個 turn
+
+### 量到的（逐字）
+
+FlowPix 依 S2 的建議把深連結改成**不帶** `prompt=`（`kenaz://connect?site=…&mcp=…&token=…&agent=claude`，142 bytes）。Kenaz 產生的 `.ps1`（token 已遮蔽）：
+
+```
+claude --mcp-config 'D:\…\kenaz-core\.mcp.json' 'C:\Users\Wei\.kenaz\agent_hub\mcp\<id>.json' --allowedTools 'mcp__127__*' --append-system-prompt-file 'C:\Users\Wei\.kenaz\agent_hub\mcp\<id>-<uuid>-persona.txt' ''
+```
+
+最後那個 `''` 就是空的 `prompt`。對照前一版（TASK_110 AC8 那次，有 prompt）的同一行結尾：
+
+```
+… -persona.txt' '先呼叫 list_canvases，然後在「生成角色裝備圖」畫布加一個 text_prompt 節點，內容寫 TASK_110 AC8'
+```
+
+### 使用者看到的
+
+- Kenaz 終端分頁：Claude Code v2.1.259 的歡迎畫面（`Opus 5 (1M context) · Claude Max`、`D:\Projects\Ashfall`）與一個空的輸入框，`manual mode on`，靜止不動。
+- FlowPix 面板：「連接中… 等待 Kenaz 連線…」直到 60 秒逾時。
+- FlowPix bridge（`http://127.0.0.1:8790`）存取紀錄：10 筆 `POST /mcp`（MCP initialize / tools/list 握手，`claude` 啟動時做的），**沒有** `kenaz_hello`、沒有 `kenaz_wait_for_message`；`GET /kenaz/connect/{token}/status` 一直是 `connected: false`。
+
+### 為什麼
+
+`claude` CLI 的位置參數是「第一則使用者訊息」。給空字串等於沒給——CLI 以互動模式起來等使用者輸入，不會自己開始一個 turn。system prompt（`--append-system-prompt-file`）只在有 turn 時才被模型讀到。因此「人格承諾在沒有 prompt 時直接進入迴圈」在機制上做不到：**沒有第一則訊息就沒有第一個 turn**。這不是人格文字的問題，是啟動方式的問題。codex 分支我們沒測；`codex` 的位置參數同樣是第一則訊息，估計行為相同。
+
+### 相關但不同層的觀察（順帶）
+
+`GET /api/agent-hub/status` 的 `sessions[0].model` 是 `claude-sonnet-5`，但終端分頁的 Claude Code 歡迎畫面顯示 `Opus 5 (1M context)`。可能是 status 回報的是 Kenaz 設定裡的 dispatch model、實際啟動沒有帶 `--model`（命令列裡確實沒有），Claude Code 用了自己的預設。不影響本報告的主題，但 `sessions[].model` 目前不能當作「這個 session 實際跑的模型」來看。
+
+## 3. FlowPix 端的自救（已做，2026-09-09）
+
+深連結重新帶一句固定的 ASCII `prompt=`，唯一目的是**觸發第一個 turn**，內容只是把人格已經承諾的事再說一次（不含任何 FlowPix 自己的迴圈邏輯）：
+
+```
+You are connected to FlowPix. Call kenaz_hello now, then keep calling kenaz_wait_for_message and act on each message with the FlowPix canvas tools; after each one, call reply with a short summary.
+```
+
+使用者的中文訊息一律走信箱（`POST /kenaz/connect/{token}/messages` → `kenaz_wait_for_message`），與 S2 的設計一致。這樣 FlowPix 不依賴本報告的修正就能運作；但每個接入的網站都得知道「一定要帶 prompt，否則 claude 不會動」，這正是 S2 想避免的 prompt 工程。
+
+## 4. 建議（給 Kenaz 側）
+
+**D1（必要）**：`launch.rs::build_interactive_script` 在 `prompt` 為空時，**不要**傳 `''`，改傳一句 Kenaz 自己的開場訊息（例如 `Session started by <site origin>. Follow the Kenaz session instructions.`），讓第一個 turn 一定發生。人格裡的「call `kenaz_hello` once before doing anything else with the prompt below」就會照常觸發，S2 的「網站可省略 prompt」才真正成立。codex 分支同理。
+
+**D2（建議）**：PROTOCOL §2 第 5 點與 SDK_GUIDE §9 的「`prompt` 省略時就直接進入」旁加註：這由 Kenaz 保證（Kenaz 會補開場訊息），網站不必自己補。
+
+**D3（建議）**：`launch.rs` 加一個測試：`prompt = None` 時產出的腳本**不**以 `''` 結尾、而是含 Kenaz 的預設開場訊息。現有的 `build_interactive_script_{claude,codex}_writes_utf8_bom_and_preserves_cjk_prompt` 只覆蓋「有 prompt」的路徑。
+
+**D4（順帶）**：`sessions[].model` 若無法保證與實際啟動一致，請回報實際命令列用的模型，或在啟動時真的帶上 `--model`。
+
+## 5. 修正後怎麼確認
+
+1. 從 FlowPix（或 `examples/minimal-site`）送一條**不帶** `prompt=` 的深連結。
+2. 審批允許後，終端分頁的 Claude Code 應自己開始第一個 turn，並呼叫 `mcp__<name>__kenaz_hello`；網站 MCP 若提供 `kenaz_wait_for_message`，接著應看到它被反覆呼叫（FlowPix bridge 的存取紀錄會出現對應的 `POST /mcp`，`GET /kenaz/connect/{token}/status` 變成 `connected: true`）。
+3. 若 Kenaz 側修好後 FlowPix 就會把第 3 節的開場 prompt 拿掉。

package/core/dev/specs/agent-connect/history/DEFECT_REPORT_kenaz-agent-hub_2026-09-09_v0.4-prompt-mojibake.md

@@ -0,0 +1,90 @@
+# Defect Report: Agent Connect v0.4 深連結的 `prompt=` 進到終端分頁後中文變亂碼（Windows / Big5 環境）
+
+日期：2026-09-09
+來源：FlowPix / GameAsset_auto（Ansuz session，TASK_110「FlowPix 接上 Kenaz Agent Connect v0.4」）
+接續：`FEATURE_REQUEST_kenaz-agent-hub_2026-09-08_relay-v1-conformance.md`、`KENAZ_RESPONSE_agent-hub_2026-09-08_...`（v0.4 定稿通知）
+Kenaz 版本觀察：kenaz-dashboard.exe **0.2.230**（`D:\Users\Wei\AppData\Local\BLOCK ACTION\kenaz-dashboard.exe`，2026-09-09 01:56 啟動，使用者環境變數 `KENAZ_AGENT_HUB_DEV=1`）。
+
+## 一句話
+
+v0.4 的深連結 → 審批卡 → 終端分頁 → `kenaz_hello` 這一整條，FlowPix 用真實 Kenaz 0.2.230 端到端驗通了（見下方「先講好消息」）。唯一的缺陷：深連結 `prompt=` 帶的中文，到了 Kenaz 開的終端分頁裡變成 Big5 解讀 UTF-8 的亂碼；ASCII 部分完整。FlowPix 端送出的深連結已逐字驗證是標準 percent-encoded UTF-8，問題在 Kenaz 把 prompt 交給 CLI 的那一步。**請 Kenaz 側在注入 prompt 時處理 Windows 主控台 codepage。**
+
+## 先講好消息：v0.4 在 FlowPix 端到端通了
+
+FlowPix 依 `dev/specs/agent-connect/SDK_GUIDE.md` §0/§1/§3 與 `PROTOCOL.md` v0.4 實作（bridge 簽一次性 token、組深連結、`/mcp` 驗 bearer、`kenaz_hello` 回 `{"ok":true}`，面板輪詢 60 秒逾時）。2026-09-09 03:50（本機時間）從 `http://localhost:5173` 按「連接 Kenaz」：
+
+- Kenaz 出審批卡，用戶按「允許」→ `GET http://127.0.0.1:18080/api/agent-hub/status` 變成 `{"origins":[{"origin":"http://localhost:5173","state":"once",...}]}`。
+- `backend.stderr.log`：`[AgentHub] Launched for http://localhost:5173 — agent=claude session=12b19338-...`。
+- Dashboard 開了終端分頁，agent 呼叫了 `mcp__127__kenaz_hello`（server 名由 `mcp=http://127.0.0.1:8790/mcp` 的 hostname 衍生成 `127`，與 SDK_GUIDE §3.3 描述一致），FlowPix 面板在幾秒內切成「Kenaz 已連線」。
+- 沒有任何 `[AgentHub] Rejected` 行；dev 模式對 `http://localhost` / `http://127.0.0.1` 的放寬如 §5 所述生效。
+
+所以深連結格式、審批卡、MCP 預配、`kenaz_hello` 慣例都符合文件。以下只有一個問題。
+
+## 問題：`prompt=` 的中文在終端分頁裡是亂碼
+
+### 用戶看到的（Kenaz 終端分頁的第一則訊息，截圖逐字）
+
+```
+?��??list_canvases曝��敺��?�??�??脰??�??��撣�?鉾??text_prompt 蜓暉�??批捆撤?TASK_110 AC8
+```
+
+FlowPix 送出的原文：
+
+```
+先呼叫 list_canvases，然後在「生成角色裝備圖」畫布加一個 text_prompt 節點，內容寫 TASK_110 AC8
+```
+
+ASCII 片段（`list_canvases`、`text_prompt`、`TASK_110 AC8`）完整無缺，只有 CJK 壞掉；壞法是「每個三位元組的 UTF-8 字元變成一個 Big5 雙位元組字加一個 `?`/`�`」——這是 UTF-8 位元組被當成 CP950 解讀的典型樣子，不是 URL 解碼錯（URL 解碼錯會出現 `Ã¥` 那種 Latin-1 樣式）。
+
+### FlowPix 端已排除（可重現）
+
+深連結由 FlowPix bridge 的 `urllib.parse.urlencode`（`quote_plus`）組出，在瀏覽器裡攔下實際送出的 URL 檢查：
+
+- `new URL(deeplink).searchParams.get('prompt') === 原文` → `true`（UTF-8 percent-encoding 正確往返）。
+- `prompt=` 的前三個位元組是 `%E5%85%88`（=「先」的 UTF-8）。
+- 整條深連結 420 bytes，`scheme=kenaz:`、`host=connect`、無 `v=`、無 `agent=`（用「依 Kenaz 預設」）。
+
+這就是 SDK_GUIDE §2「URL 編碼規則：每個參數值都要 encodeURIComponent」的做法；FlowPix 沒有別的方式可以送中文。
+
+### 本機環境（Kenaz 重現時要對齊的變數）
+
+| 項目 | 值 |
+|---|---|
+| OS | Windows 11 Pro 10.0.26200 |
+| 系統 ANSI / OEM codepage | `ACP=950`、`OEMCP=950`（繁中 Big5） |
+| PowerShell `[Console]::InputEncoding` / `OutputEncoding` | `big5` / `big5` |
+| Culture / UICulture | `en-US` / `zh-TW` |
+| `claude` 解析到的執行檔 | `C:\Users\Wei\AppData\Roaming\npm\claude.ps1`（npm 的 PowerShell shim），`claude --version` = `2.1.259` |
+| 使用的 agent | `agent=` 省略 → Kenaz 預設，實際啟動 claude |
+
+### 推測的出錯點（Rust 原始碼不在這台機器，請以原始碼核對）
+
+深連結在 `deep_link.rs` 用 `Url` 解析，`prompt` 進到 Rust 時應已是正確的 UTF-8 `String`（否則 ASCII 也不會完整）。壞掉發生在「把 prompt 交給 CLI」這一步，兩種可能：
+
+1. **prompt 以 argv 傳給 `claude`**：`claude` 在這台機器解析到 `claude.ps1`，經 `powershell.exe` 轉手時參數以 ANSI codepage（950）重新編碼，或是 spawn 用了 ANSI 版 API。
+2. **prompt 以按鍵/stdin 方式寫進終端分頁（PTY）**：Kenaz 寫入的是 UTF-8 位元組，但該主控台的輸入 codepage 是 950（Windows 預設跟著 OEMCP），shell/CLI 以 Big5 解讀。
+
+### 需求
+
+**D1（必要）**：在 Windows 上讓 `prompt=` 的非 ASCII 內容原樣到達 agent。可行做法擇一：
+- 注入前先把該終端分頁的 codepage 設成 UTF-8（等同 `chcp 65001`，或 `SetConsoleCP/SetConsoleOutputCP(65001)`），再寫入 UTF-8 位元組；
+- 或依目前主控台的輸入 codepage 轉碼後再寫入；
+- 或不經 argv/PTY 文字，改把 prompt 寫進 UTF-8 暫存檔、以 `claude -p`/`codex exec` 的檔案或 stdin 方式餵入（`codex exec` 本來就支援 stdin prompt）；
+- 若走 argv，直接 spawn `node <claude cli.js>` 或 `claude.cmd`，避開 `claude.ps1` 這層 PowerShell shim，並用寬字元 CreateProcessW。
+
+**D2（建議）**：SDK_GUIDE §2「長度限制」旁補一句「`prompt` 支援任意 UTF-8，Windows 上由 Kenaz 負責 codepage」，讓網站開發者不用自己猜要不要先轉成 ASCII。
+
+**D3（建議）**：conformance suite（`dashboard/scripts/agent-connect-conformance/run.mjs`）加一個含 CJK 的 `deep_link.*` fixture，並在 Windows CI 上驗「agent 收到的第一則訊息 == fixture 的 prompt」。
+
+### 影響
+
+FlowPix 的產品設計（用戶決定，2026-09-09）是「生圖改成 prompt 裡描述，agent 用 FlowPix 的 MCP 工具產出並寫回畫布」，用戶是中文使用者，`prompt=` 幾乎一定含中文。目前 workaround 只有把 prompt 限制成英文，或改成「深連結只帶一句英文、真正的指示放進 FlowPix MCP 的工具讓 agent 自己拿」——後者 SDK_GUIDE §2 本來就建議用於長內容，FlowPix 可以做，但短中文 prompt 壞掉仍是 Kenaz 端該修的。
+
+## 怎麼重現（Kenaz 側）
+
+1. Windows、系統語言繁中（ACP 950），`KENAZ_AGENT_HUB_DEV=1` 完整重啟 Kenaz 0.2.230。
+2. `cd D:\Projects\GameAsset_auto && .\dev.ps1`（或只起 bridge `python -m uvicorn bridge.main:app --port 8790` + `cd editor && npx vite --port 5173`）。
+3. 瀏覽器開 `http://localhost:5173`，工具列右下「連接 Kenaz」→ 在「要 agent 做什麼」輸入任何中文 → 按「連接 Kenaz」→ 審批卡按允許。
+4. 看終端分頁的第一則訊息；同時 FlowPix 面板應顯示「Kenaz 已連線」（證明其餘流程正常）。
+
+沒有 Kenaz 也能看到 FlowPix 送了什麼：`curl -X POST http://127.0.0.1:8790/kenaz/connect -H 'content-type: application/json' -d '{"site":"http://localhost:5173","prompt":"測試"}'`，回應的 `deeplink` 裡 `prompt=%E6%B8%AC%E8%A9%A6`。

package/core/dev/specs/agent-connect/history/FEATURE_REQUEST_kenaz-agent-hub_2026-09-07.md

@@ -0,0 +1,61 @@
+# Feature Request: Kenaz 作為網站可喚起的本機 Agent（Agent Hub）
+
+日期：2026-09-07
+來源：FlowPix / GameAsset_auto（Ansuz session）
+Kenaz 版本觀察：kenaz-dashboard.exe 0.2.228，本機 MCP 於 `http://localhost:18080/api/mcp`，**尚未註冊任何 URL 協定**（HKCU/HKLM `Software\Classes` 皆無 `kenaz`）。
+
+## 目標（一句話）
+
+雲端網站（第一個是 FlowPix）按「連接 Kenaz」就能喚起用戶電腦上的 Kenaz，之後網站的 AI 生成請求由 Kenaz 用**用戶自己的 Codex（ChatGPT 訂閱）**執行，用戶在 Kenaz 的彈窗裡審批。網站與伺服器永遠碰不到用戶的憑證，也不付 AI 的錢。體驗對齊 Web3「連接錢包」：連接一次、每次操作審批、可設「此網站永遠允許」。
+
+## 美術人員看到的流程（驗收基準）
+
+1. 網站按「連接 Kenaz」→ 若未安裝，導到下載頁；一鍵安裝。
+2. 瀏覽器詢問「要開啟 Kenaz 嗎？」→ 確定 → 網站顯示「已連線」。
+3. 第一次生成 → Kenaz 開啟 ChatGPT 登入頁（內部是 `codex login`）→ 登入完成。
+4. 之後每次生成 → 右下角彈窗「flowpix.app 要用你的 Codex 生成 1 張圖：允許／此網站永遠允許／拒絕」。
+
+沒有終端、沒有 token、沒有 Node、沒有 git。
+
+## Kenaz 側要新增的能力
+
+| # | 能力 | 說明 | 現況 |
+|---|---|---|---|
+| K1 | `kenaz://` URL 協定 | 安裝程式註冊（Windows：`HKCU\Software\Classes\kenaz`，`URL Protocol` + `shell\open\command`；macOS：`CFBundleURLTypes`）。Tauri 2 有 `tauri-plugin-deep-link`，含單一實例轉發（已在跑的 Kenaz 收到 URL 而不是再開一個）。 | 缺 |
+| K2 | 配對與對外連線 | 處理 `kenaz://connect?site=<origin>&token=<一次性>&relay=<wss url>`：以 token 向 relay 換取 session 憑證，之後**主動**維持一條 WSS 到 relay（用戶端只做對外連線；防火牆友善）。斷線退避重連。 | 缺 |
+| K3 | 站點權限與審批 UI | 每個 origin 一筆授權紀錄（未授權／單次／永遠允許／封鎖）。收到需要審批的請求時彈原生視窗或 toast，含請求摘要（哪個網站、做什麼、預估數量）。審批結果與狀態要回報給網站（見協定 `approval/*`）。 | 缺 |
+| K4 | Codex 驅動（app-server） | 由 Kenaz 啟動並持有 `codex app-server --listen ws://127.0.0.1:<port>`，以 JSON-RPC 走 `initialize` → `thread/start {ephemeral:true, sandbox:"read-only", approvalPolicy:"never"}` → `turn/start`；`item/completed` 的 `imageGeneration` item 帶 `result`（base64 PNG）與 `savedPath`；`account/rateLimits/updated` 回報訂閱用量。已在 FlowPix 實測：一輪約 35 秒；**app-server 對任何帶 Origin 的握手回 403，所以只能由 Kenaz 這種本機程序連，網頁不可能直連**。參考：GameAsset_auto 的 rune `rune_545535f080244e4084d1573309bfc4e3`、`rune_f352dc3d2dce4dc2969fa6a769da371b`。 | Kenaz 已能派工給 Codex（formation adapter），但不是這條長連線協定 |
+| K5 | Codex 執行檔與登入 | 隨附 Codex 執行檔（`@openai/codex` 為 Apache-2.0，npm 套件內含各平台二進位），不要求用戶裝 Node；首次使用由 Kenaz 觸發 `codex login`（開瀏覽器），並偵測 `codex login status` 是否「Logged in」。 | 缺 |
+| K6 | 極簡 bundle | 同一 Tauri 程式碼庫用 feature flag 切出「FlowPix Agent」bundle：只有 tray、深連結、K2–K5，沒有 Dashboard 介面。完整版 Kenaz Dashboard 內含同一模組。 | 缺 |
+| K7 | tray、開機自啟、自動更新 | `tauri-plugin-autostart`、`tauri-plugin-updater`；更新來源可放靜態空間（Cloudflare Pages）。 | 未核實（原始碼不在本機） |
+| K8 | 依用戶選擇啟動 CLI Agent（**用戶 2026-09-07 追加，核心需求**） | 深連結多帶 `agent=claude\|codex`（可再帶 `task=<id>` 或初始 prompt）。Kenaz 喚起後啟動用戶選的 CLI：`claude`（Claude Code）或 `codex`，並**預先接好 FlowPix 的 MCP 端點與這次配對的憑證**（Claude：`claude mcp add --transport http flowpix <url> --header "Authorization: Bearer <session>"` 的等價設定；Codex：`mcp_servers.flowpix.url` + bearer env），讓 Agent 一啟動就能用 FlowPix 的畫布工具集（list_canvases…focus_canvas）與生成。兩種模式：`interactive`（開一個終端視窗，用戶看得到、能對話）與 `headless`（Kenaz 代跑 `claude -p` / `codex exec`，結果回網站）。Kenaz 既有的 Claude/Codex dispatch adapter 可重用。生圖仍走 K4 的 Codex；選 Claude Code 時 Claude 負責畫布協作、生圖節點由 Kenaz 交給 Codex。若所選 CLI 未安裝或未登入，回報 `agent_unavailable` 並在 Kenaz 內引導安裝/登入。 | Kenaz 已能派工給兩者，但沒有「從深連結參數啟動並預配 MCP」 |
+
+## 協定契約（Relay v1，Kenaz 與網站雙方都照這份實作）
+
+> **定稿位置（2026-09-07 更新）**：FlowPix repo `D:/Projects/GameAsset_auto/bridge/CONTRACT.md` 的「Relay v1」章節，已由 spike TASK_105 用真實 Codex 端到端驗通（relay 訊息 17 則、最大 300 bytes，圖片走 blobstore URL；token 一次性/60 秒/綁 origin 三種拒絕都有測試；Claude Code 與 Codex 兩種 CLI 都能由 agent.launch 啟動並用預配的 MCP 在畫布加節點）。K1–K8 對照表在 `spikes/relay_spike/NOTES.md`。假 Kenaz 的參考實作：`bridge/agent_relay_client.py`（Python，Kenaz 以 Rust 重寫時逐訊息對照）。下面的骨架以那份為準。
+
+由 FlowPix 側先用現有的 Python bridge 當「假 Kenaz」驗通，再由 Kenaz 以 Rust 實作。定稿版本會放在 FlowPix repo `bridge/CONTRACT.md` 的「Relay v1」章節，這裡先列骨架：
+
+- 傳輸：WSS，JSON 訊息，每則含 `type`、`request_id`（呼叫／回應配對），大於 1 MB 的圖片以物件儲存（R2/GCS）presigned URL 傳遞而非內嵌。
+- 配對：`pair.begin {token}` → `pair.ok {session_credential, site_origin}`；token 一次性、60 秒 TTL、綁定 origin。
+- 狀態：`agent.status {codex_logged_in, rate_limits?, approval_mode}` 主動推送。
+- 請求（relay → Kenaz）：`generate_image {prompt, size, quality, reference_images:[url]}`、`generate_text {...}`；FlowPix 的畫布工具集（`list_canvases`…`focus_canvas`，見 Agent hub v1）保留給本機 CLI Agent 路徑，不經 relay。
+- 審批：Kenaz 在執行前推 `approval.pending {request_id, summary}`，用戶決定後推 `approval.resolved {request_id, decision}`，網站據此顯示「等待你在 Kenaz 允許」。
+- 結果：`result {request_id, ok, payload | error:{code,message}}`；錯誤碼含 `not_logged_in`、`usage_limit_exceeded`（附 resetsAt）、`denied`、`timeout`。
+- 安全：Kenaz 只做對外連線；憑證不離開本機；session 憑證可由用戶在 Kenaz 內撤銷；每個 origin 獨立授權。
+
+## 已知限制（先講清楚）
+
+- Codex 內建 `image_gen` 對**正方形**尺寸一律回 1254x1254（非正方形照做）；網站端要能接受實際尺寸。
+- Codex 的 `remote-control` 是 OpenAI 自家客戶端的中繼，對第三方不開放；若未來開放，K2 的 relay 可換成它。
+- 一台機器同時開多個網站分頁時，審批要能標明是哪個 origin 的哪個請求。
+
+## FlowPix 側對應工作（不需 Kenaz 動手）
+
+- 雲端 backend：引擎跑到 AI 節點時暫停、把請求經 relay 送到該用戶的 Kenaz、收到結果續跑（Ansuz 建為 spike 卡）。
+- 網站：「連接 Kenaz」按鈕（喚起 `kenaz://connect?...`）、連線與審批狀態顯示、未安裝時的下載導引。
+- relay 服務：先用本機 Node ws 原型，通了再放雲端。
+
+## 聯絡點
+
+FlowPix 側的既有實作可直接參考：`bridge/`（provider 插槽、Agent hub、Codex 呼叫）、`spikes/ai_bridge/`、`spikes/agent_hub/`。

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

@@ -0,0 +1,76 @@
+# Defect / Change Request: Agent Hub 與 Relay v1 合約不一致，且本機開發環境無法配對
+
+日期：2026-09-08
+來源：FlowPix / GameAsset_auto（Ansuz session）
+接續：`FEATURE_REQUEST_kenaz-agent-hub_2026-09-07.md`（K1–K8）
+Kenaz 版本觀察：kenaz-dashboard.exe **0.2.229**（`D:\Users\Wei\AppData\Local\BLOCK ACTION\kenaz-dashboard.exe`，2026-09-08 06:05 建置），`GET /api/health` 回 `"version":"0.2.229"`。
+
+## 一句話
+
+K1 已通（`kenaz://` 到得了正在跑的 Kenaz），但 Agent Hub 在撥 relay 之前就用三道 scheme 閘門把本機開發環境擋掉；而且 exe 內的訊息型別與 FlowPix 的定稿合約 `D:/Projects/GameAsset_auto/bridge/CONTRACT.md`「Relay v1」章節有多處欄位漂移。**請 Kenaz 側對齊合約**（合約是 2026-09-07 用真實 Codex 端到端驗通的版本，FlowPix 的 backend / relay / 假 Kenaz 三方都以它為準，`test_relay_contract.py` 鎖住），並提供 loopback 開發模式。
+
+## 怎麼測的（可重現）
+
+1. 起 FlowPix 的 relay 原型：`node spikes/relay_spike/relay.mjs --port 8791 --log <path>`（relay 會把每一則 frame 的方向 / type / bytes 記成 JSONL）。
+2. 以「site」角色連上 relay：`site.hello {origin}` → `token.mint {agent:null}` → 拿到一次性 token，組出深連結。
+3. 開深連結（兩種方式都試過）：`os.startfile("kenaz://connect?...")`（走 OS 協定處理器），以及直接 `kenaz-dashboard.exe "kenaz://connect?..."`。
+4. 觀察三處：relay 的 frame log、`GET http://localhost:18080/api/agent-hub/status`、`C:\Users\Wei\AppData\Local\Kenaz Dashboard\backend.stderr.log`。
+
+三次結果：relay **從未**收到任何來自 Kenaz 的連線（frame log 只有 site 自己的 4 則）；`/api/agent-hub/status` 始終 `{"origins":[],"relay":{"status":"disconnected"}}`；stderr log 出現：
+
+```
+[AgentHub] Rejected deep link (site scheme not allowed: http): kenaz://connect/?site=http%3A%2F%2F127.0.0.1%3A5173&token=...&relay=ws%3A%2F%2F127.0.0.1%3A8791%2Fws
+[AgentHub] Rejected deep link (site scheme not allowed: http): kenaz://connect?site=http%3A%2F%2F127.0.0.1%3A5173&token=...&relay=ws%3A%2F%2F127.0.0.1%3A8791%2Fws
+[AgentHub] Rejected deep link (relay scheme not allowed: ws): kenaz://connect?site=https%3A%2F%2F127.0.0.1%3A5173&token=...&relay=ws%3A%2F%2F127.0.0.1%3A8791%2Fws
+```
+
+（第一行的 `connect/?` 是 OS 協定處理器正規化加的斜線，Kenaz 兩種寫法都有正確解析，這點沒問題。）
+
+## 問題 1：三道 scheme 閘門讓本機開發完全無法配對（阻斷）
+
+exe 內有三個拒絕訊息：`site scheme not allowed: `、`relay scheme not allowed: `、`mcp scheme not allowed: `。FlowPix 開發環境是 editor `http://localhost:5173`、relay `ws://127.0.0.1:8791/ws`、bridge MCP `http://127.0.0.1:8790/mcp`，三個都會被擋。
+
+**需求 D1**：提供開發模式豁免，只對 loopback 生效（`127.0.0.1` / `localhost` / `[::1]`），允許 `http` / `ws`。建議形式：環境變數（例如 `KENAZ_AGENT_HUB_ALLOW_INSECURE_LOOPBACK=1`）或 Dashboard 設定開關，預設關閉。正式環境維持 https / wss 強制，這點我們同意。
+**需求 D2**：拒絕深連結時，除了寫 stderr，也要把原因顯示給用戶（toast 或 Dashboard 內通知）。現在網站端只看到「已開啟 Kenaz」但永遠不會變成「已連線」，用戶無從得知是哪裡被擋。
+
+## 問題 2：訊息型別與 Relay v1 合約漂移
+
+以下「Kenaz 實作」欄位是從 0.2.229 exe 的 serde 字串表還原（`internally tagged enum AgentHubMessage`，欄位名與 `struct variant ... with N elements` 的 N），因為 Rust 原始碼不在這台機器上；請以原始碼核對，但欄位名本身是實際存在於二進位裡的。
+
+| 訊息 | Relay v1 合約（CONTRACT.md §） | Kenaz 0.2.229 實作 | 需求 |
+|---|---|---|---|
+| 配對拒絕 | `pair.denied {request_id, error:{code,message}}`（§3），code ∈ token_invalid / token_expired / token_already_used / origin_mismatch / relay_unavailable | `pair.error {request_id, code, message}`（3 elements） | **D3** 改回 `pair.denied`，error 包在 `error` 物件內。相關字串 `timeout waiting for pair.ok/pair.error` 一併改。 |
+| 狀態推送 | `agent.status {request_id:null, codex_logged_in, rate_limits, approval_mode}`（§4） | `agent.status {agents, dispatch, approval_mode, ...}`（4 elements） | **D4** 至少保留 `codex_logged_in`（bool）與 `rate_limits`（nullable）；`agents` / `dispatch` 可以額外附加，FlowPix 會忽略未知欄位。 |
+| 生圖請求 | `generate_image {request_id, prompt, size, quality, reference_images:[url]}`（§5） | `generate_image {request_id, prompt, input_url}`（3 elements） | **D5** 接受合約的 `size` / `quality` / `reference_images[]`（多張參考圖是 FlowPix 既有節點的真實需求）。`input_url` 單張欄位若要保留可當 alias。 |
+| 生文請求 | `generate_text {request_id, prompt, system, model, max_output_tokens, reasoning_effort, reference_images:[url]}`（§5） | `generate_text {request_id, prompt}`（2 elements） | **D6** 接受合約欄位（至少 `system`、`max_output_tokens`、`reference_images`）。若 serde 用 `deny_unknown_fields`，現在合約訊息會直接被拒。 |
+| 生成結果 | `result {request_id, ok, payload}`；image payload `{url, width, height, provider, elapsed_ms, meta}`、text payload `{text, provider, elapsed_ms, meta}`（§7） | `result {request_id, ok, ...}`（4 elements）；另有 hub prompt 要求 agent 寫 `{ok, text, artifacts:[{url,kind}]}` | **D7** `generate_*` 的 result 請照 §7 的 payload 形狀；`{ok,text,artifacts}` 只用於 `agent.launch` 的回覆即可。**圖片一律走 URL**（relay 有 256 KiB 單則上限，§Transport）。 |
+| 錯誤碼 | not_logged_in / usage_limit_exceeded(+resetsAt) / denied / timeout / relay_unavailable / payload_too_large（§7） | denied / agent_unavailable / mcp_config_failed / launch_failed / timeout | **D8** 補 `not_logged_in` 與 `usage_limit_exceeded {resetsAt}`（網站要據此顯示「請先登入 ChatGPT」/「用量已達上限，xx 時重置」）。新增的三個碼我們會接受。 |
+| Agent 啟動 | Kenaz → 網站的**公告**：`agent.launch {agent, mode, prompt}` → `agent.launched {agent, pid}` \| `agent_unavailable {agent, reason}`（§8）；由深連結的 `agent=` 觸發 | 網站 → Kenaz 的**請求**：`agent.launch {request_id, agent, model?, prompt, mcp, cwd}`（6 elements），以 `result` 回覆 | **D9** 兩種語意都可以，但要二選一並寫進合約。若 Kenaz 堅持「網站請求」語意，請告知確切欄位與 `result` 形狀，FlowPix 會改 backend；深連結的 `agent=` 參數仍要能在配對成功後自動啟動一次（美術人員按一次「連接」就該看到 CLI 起來，這是 K8 的核心體驗）。 |
+| 配對成功 | `pair.ok {request_id, session_credential, site_origin}`（§3） | `pair.ok`（3 elements，含 `session_credential`） | 看起來一致，請確認。 |
+| 審批 | `approval.pending {request_id, summary}` / `approval.resolved {request_id, decision}`（§6） | 同名同欄位數 | 一致。 |
+
+## 問題 3：深連結多了 `mcp` 參數，合約沒有
+
+Kenaz 的 `agent_hub/sites.json` 每筆有 `origin, session_credential, relay_url, paired_at, last_used_at, mcp_url, last_agent` 與權限 `unauthorized | once | always`（K3 的持久化權限表，很好）。`mcp_url` 顯然來自深連結的 `mcp=` 參數，合約的深連結只有 `site / token / relay / agent`（§2）。
+
+**需求 D10**：請確認 `mcp=` 是否必填、以及 `mcp` 缺席時是否仍能完成配對與 `generate_*`（生圖不需要 MCP）。FlowPix 願意加 `mcp=<bridge /mcp url>`，但它必須是**選填**，且受問題 1 的 loopback 豁免（開發時是 `http://127.0.0.1:8790/mcp`）。合約會在你們確認後更新 §2。
+
+## 有做對的（不用改）
+
+- K1：`tauri-plugin-deep-link` + single-instance 轉發正常，兩種喚起方式都到達正在跑的實例。
+- K3：`sites.json` 的 per-origin 權限模型（`unauthorized | once | always`）符合需求。
+- K8：core 腳本端 `hub` formation（`.formation/unit/hub.yaml`）+ `headless.js --mcp-config-extra / --allowed-tools` + `relay.js buildCodexMcpOverrides`（bearer 走環境變數，不進 `-c` 字面值）——設計正確，測試也在。
+- TLS：native-tls / schannel，正式環境的 wss 憑證鏈不會有問題。
+
+## 驗收方式（Kenaz 修完後 FlowPix 這邊會跑）
+
+1. `KENAZ_AGENT_HUB_ALLOW_INSECURE_LOOPBACK=1` 下，用上面的重現步驟，relay frame log 要出現 Kenaz 的 `pair.begin` → relay 回 `pair.ok` → Kenaz 推 `agent.status`，`/api/agent-hub/status` 的 `origins` 出現 `https?://127.0.0.1:5173`。
+2. 送一則合約形狀的 `generate_text`，Kenaz 要先推 `approval.pending`（在做任何事之前），用戶允許後推 `approval.resolved`，最後 `result.ok=true` 且 `payload.text` 有值。
+3. 送一則帶兩張 `reference_images` URL 的 `generate_image`，`result.payload.url` 可下載、`width/height` 為實際尺寸。
+4. 錯誤 token 重放：relay 回 `pair.denied {error.code:"token_already_used"}`，Kenaz 要正確解析並顯示，而不是 `timeout waiting for pair.ok/pair.error`。
+
+## 聯絡點
+
+- 合約：`D:/Projects/GameAsset_auto/bridge/CONTRACT.md`「Relay v1」章節（欄位名逐一對照；`spikes/relay_spike/test_contract_consistency.py` 鎖三方一致）。
+- 參考實作：`bridge/agent_relay_client.py`（假 Kenaz，逐訊息對照）、`spikes/relay_spike/relay.mjs`（token 一次性 / 60 秒 / 綁 origin 的參考行為）。
+- 本次探針腳本與 relay frame log：Ansuz session scratchpad `site_probe.py`、`relay_frames.jsonl`、`probe1..3.log`（需要可再提供）。