kenaz 0.3.22 → 0.3.23

package/core/dev/scripts/sync_task_queue.sh

@@ -1,392 +0,0 @@
-#!/usr/bin/env bash
-# ============================================================
-# Sync Task Queue (macOS/Linux version)
-# ============================================================
-# Read YAML/Markdown task files and sync to TASK_QUEUE.json
-# Equivalent of sync_task_queue.ps1
-# ============================================================
-
-set -euo pipefail
-
-# --- Parameters ---
-WORKING_DIRECTORY=""
-FORCE=false
-QUIET=false
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --working-directory|--wd) WORKING_DIRECTORY="$2"; shift 2 ;;
-        --force) FORCE=true; shift ;;
-        --quiet) QUIET=true; shift ;;
-        --nopause) QUIET=true; shift ;;
-        *) shift ;;
-    esac
-done
-
-# Use KENAZ_PROJECT_PATH env var if WorkingDirectory not specified
-if [[ -z "$WORKING_DIRECTORY" ]]; then
-    if [[ -n "${KENAZ_PROJECT_PATH:-}" ]]; then
-        WORKING_DIRECTORY="$KENAZ_PROJECT_PATH"
-    else
-        WORKING_DIRECTORY="$(pwd)"
-    fi
-fi
-
-TASKS_DIR="$WORKING_DIRECTORY/dev/pipeline/tasks"
-COMPLETED_DIR="$WORKING_DIRECTORY/dev/pipeline/completed"
-QUEUE_FILE="$WORKING_DIRECTORY/dev/pipeline/TASK_QUEUE.json"
-
-# --- Logging ---
-info() { [[ "$QUIET" == "true" ]] || echo "  $1"; }
-success() { [[ "$QUIET" == "true" ]] || echo "  OK $1"; }
-warn() { echo "  [WARN] $1" >&2; }
-
-# --- JSON helper via python3 ---
-# We use python3 for all JSON operations since jq may not be installed
-py_json() {
-    python3 -c "$1"
-}
-
-# --- Parse a YAML task file (simple regex-based) ---
-parse_yaml_task() {
-    local filepath="$1"
-    local filename
-    filename=$(basename "$filepath")
-
-    python3 << 'PYEOF' "$filepath" "$filename"
-import sys, re, json, os
-from datetime import datetime
-
-filepath = sys.argv[1]
-filename = sys.argv[2]
-
-with open(filepath, 'r', encoding='utf-8') as f:
-    content = f.read()
-
-# Extract task ID from filename
-m = re.match(r'^(TASK_\d+)', filename)
-if not m:
-    sys.exit(1)
-task_id = m.group(1)
-
-# Parse YAML fields
-def extract(pattern, default=''):
-    m = re.search(pattern, content, re.MULTILINE)
-    return m.group(1).strip().strip('"') if m else default
-
-title = extract(r'^title:\s*"?([^"\r\n]+)"?')
-priority = extract(r'^priority:\s*"?(P[0-3])"?', 'P2')
-status = extract(r'^status:\s*"?([^"\r\n]+)"?', 'pending')
-agent_type = extract(r'^agent_type:\s*"?([^"\r\n]+)"?', 'dev')
-created_at = extract(r'^\s*created_at:\s*"?([^"\r\n]+)"?', datetime.now().isoformat())
-est_hours = extract(r'^estimated_hours:\s*(\d+\.?\d*)', '')
-
-# Description - handle multiline with | or single line
-description = ''
-m = re.search(r'^description:\s*\|?\s*\n((?:[ \t]+[^\n]*\n?)+)', content, re.MULTILINE)
-if m:
-    description = re.sub(r'(?m)^[ \t]+', '', m.group(1)).replace('\n', ' ').strip()
-    if len(description) > 200:
-        description = description[:197] + '...'
-else:
-    description = extract(r'^description:\s*"?([^"\r\n]+)"?')
-
-# Parse dependencies array
-dependencies = []
-m = re.search(r'^dependencies:\s*\n((?:[ \t]*-[^\n]*\n?)+)', content, re.MULTILINE)
-if m:
-    dependencies = re.findall(r'-\s*"?(TASK_\d+)"?', m.group(1))
-
-# Parse scope_paths array
-scope_paths = []
-m = re.search(r'^scope_paths:\s*\n((?:[ \t]*-[^\n]*\n?)+)', content, re.MULTILINE)
-if m:
-    scope_paths = [p.strip().strip('"') for p in re.findall(r'-\s*"?([^"\n]+)"?', m.group(1))]
-
-if not scope_paths:
-    scope_paths = ['src/']
-
-# Skill path mapping
-skill_map = {
-    'developer': '.claude/skills/developer/SKILL.md',
-    'backend': '.claude/skills/backend_engineer/SKILL.md',
-    'designer': '.claude/skills/designer/SKILL.md',
-    'qa': '.claude/skills/qa_engineer/SKILL.md',
-    'sre': '.claude/skills/sre_agent/SKILL.md',
-    'dev': '.claude/skills/dev_agent/SKILL.md',
-    'frontend': '.claude/skills/frontend_agent/SKILL.md',
-    'architect': '.claude/skills/architect_agent/SKILL.md',
-}
-skill_path = skill_map.get(agent_type, '.claude/skills/dev_agent/SKILL.md')
-
-task = {
-    'id': task_id,
-    'title': title,
-    'description': description,
-    'priority': priority,
-    'status': status,
-    'scope_paths': scope_paths,
-    'dependencies': dependencies,
-    'source_file': filename,
-    'created_at': created_at,
-    'agent_type': agent_type,
-    'skill_path': skill_path,
-}
-if est_hours:
-    task['estimated_hours'] = float(est_hours)
-
-print(json.dumps(task))
-PYEOF
-}
-
-# --- Parse a Markdown task file ---
-parse_md_task() {
-    local filepath="$1"
-    local filename
-    filename=$(basename "$filepath")
-
-    python3 << 'PYEOF' "$filepath" "$filename"
-import sys, re, json
-from datetime import datetime
-
-filepath = sys.argv[1]
-filename = sys.argv[2]
-
-with open(filepath, 'r', encoding='utf-8') as f:
-    content = f.read()
-
-# Extract task ID
-m = re.match(r'^(TASK_\d+)', filename)
-if not m:
-    sys.exit(1)
-task_id = m.group(1)
-
-# Title from first heading
-title = ''
-m = re.search(r'^#\s+(.+?)(?:\n|$)', content, re.MULTILINE)
-if m:
-    title = re.sub(rf'^{re.escape(task_id)}:\s*', '', m.group(1)).strip()
-
-# Priority
-priority = 'P2'
-m = re.search(r'\b(P[0-3])\b', content)
-if m:
-    priority = m.group(1)
-
-# Scope paths
-scope_paths = []
-for kw in ['dashboard/', 'src/', 'app/', 'components/', 'api/', 'tests/']:
-    if kw in content:
-        scope_paths.append(kw)
-if not scope_paths:
-    scope_paths = ['src/']
-scope_paths = list(set(scope_paths))
-
-# Dependencies
-task_num = int(re.search(r'\d+', task_id).group())
-deps = []
-for m in re.finditer(r'TASK_(\d+)', content):
-    dep_id = f'TASK_{m.group(1)}'
-    dep_num = int(m.group(1))
-    if dep_id != task_id and dep_num < task_num and dep_id not in deps:
-        deps.append(dep_id)
-
-# Infer agent type
-title_lower = title.lower()
-agent_type = 'dev'
-for kw in ['ui', 'ux', 'layout', 'style', 'design', 'css', 'theme', 'color']:
-    if kw in title_lower:
-        agent_type = 'designer'; break
-else:
-    for kw in ['api', 'database', 'backend', 'endpoint', 'server', 'sql', 'migration']:
-        if kw in title_lower:
-            agent_type = 'backend'; break
-    else:
-        for kw in ['test', 'qa', 'quality', 'e2e', 'spec']:
-            if kw in title_lower:
-                agent_type = 'qa'; break
-        else:
-            for kw in ['deploy', 'ci/cd', 'monitoring', 'infrastructure', 'docker']:
-                if kw in title_lower:
-                    agent_type = 'sre'; break
-            else:
-                for kw in ['component', 'react', 'frontend', 'tsx', 'jsx', 'hook', 'state']:
-                    if kw in title_lower:
-                        agent_type = 'developer'; break
-
-skill_map = {
-    'developer': '.claude/skills/developer/SKILL.md',
-    'backend': '.claude/skills/backend_engineer/SKILL.md',
-    'designer': '.claude/skills/designer/SKILL.md',
-    'qa': '.claude/skills/qa_engineer/SKILL.md',
-    'sre': '.claude/skills/sre_agent/SKILL.md',
-    'dev': '.claude/skills/dev_agent/SKILL.md',
-}
-skill_path = skill_map.get(agent_type, '.claude/skills/dev_agent/SKILL.md')
-
-print(json.dumps({
-    'id': task_id,
-    'title': title,
-    'priority': priority,
-    'status': 'pending',
-    'scope_paths': scope_paths,
-    'dependencies': deps,
-    'source_file': filename,
-    'created_at': datetime.now().isoformat(),
-    'agent_type': agent_type,
-    'skill_path': skill_path,
-}))
-PYEOF
-}
-
-# ============================================================
-# Main
-# ============================================================
-
-if [[ "$QUIET" != "true" ]]; then
-    echo ""
-    echo "============================================================"
-    echo "       Syncing Task Queue"
-    echo "============================================================"
-    echo ""
-fi
-
-# Ensure tasks directory exists
-if [[ ! -d "$TASKS_DIR" ]]; then
-    warn "Tasks directory not found: $TASKS_DIR"
-    exit 0
-fi
-
-info "Scanning tasks from: $TASKS_DIR (only pending/in_progress/blocked tasks)"
-
-# Collect all task JSON objects into a temp file
-TASKS_TMPFILE=$(mktemp /tmp/kenaz_tasks.XXXXXX)
-trap "rm -f '$TASKS_TMPFILE'" EXIT
-
-# Process YAML files
-for f in "$TASKS_DIR"/TASK_*.yaml "$TASKS_DIR"/TASK_*.yml; do
-    [[ -f "$f" ]] || continue
-    task_json=$(parse_yaml_task "$f" 2>/dev/null || echo "")
-    if [[ -n "$task_json" ]]; then
-        echo "$task_json" >> "$TASKS_TMPFILE"
-        task_id=$(echo "$task_json" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
-        task_title=$(echo "$task_json" | python3 -c "import sys,json; print(json.load(sys.stdin)['title'])")
-        task_pri=$(echo "$task_json" | python3 -c "import sys,json; print(json.load(sys.stdin)['priority'])")
-        info "  Found (yaml): $task_id - $task_title [$task_pri]"
-    fi
-done
-
-# Process Markdown files
-for f in "$TASKS_DIR"/TASK_*.md; do
-    [[ -f "$f" ]] || continue
-    task_json=$(parse_md_task "$f" 2>/dev/null || echo "")
-    if [[ -n "$task_json" ]]; then
-        echo "$task_json" >> "$TASKS_TMPFILE"
-        task_id=$(echo "$task_json" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
-        task_title=$(echo "$task_json" | python3 -c "import sys,json; print(json.load(sys.stdin)['title'])")
-        task_pri=$(echo "$task_json" | python3 -c "import sys,json; print(json.load(sys.stdin)['priority'])")
-        info "  Found (md): $task_id - $task_title [$task_pri]"
-    fi
-done
-
-info "Skipping completed/ directory (completed tasks are managed in .memory/)"
-
-# Merge and generate final TASK_QUEUE.json via Python
-python3 << 'PYEOF' "$TASKS_TMPFILE" "$QUEUE_FILE" "$FORCE"
-import sys, json, os
-from datetime import datetime
-
-tasks_file = sys.argv[1]
-queue_file = sys.argv[2]
-force = sys.argv[3] == 'true' if len(sys.argv) > 3 else False
-
-# Read scanned tasks
-tasks = []
-if os.path.exists(tasks_file):
-    with open(tasks_file, 'r') as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                try:
-                    tasks.append(json.loads(line))
-                except json.JSONDecodeError:
-                    pass
-
-# Load existing queue for merge
-existing_tasks = {}
-if os.path.exists(queue_file) and not force:
-    try:
-        with open(queue_file, 'r', encoding='utf-8') as f:
-            existing = json.load(f)
-            for t in existing.get('tasks', []):
-                existing_tasks[t['id']] = t
-    except (json.JSONDecodeError, KeyError):
-        pass
-
-# Merge
-merged = []
-for task in tasks:
-    tid = task['id']
-    if tid in existing_tasks and not force:
-        ex = existing_tasks[tid]
-        # Preserve non-pending status
-        if ex.get('status') and ex['status'] != 'pending':
-            task['status'] = ex['status']
-        # Preserve description if not in new
-        if not task.get('description') and ex.get('description'):
-            task['description'] = ex['description']
-        # Preserve estimated_hours
-        if ex.get('estimated_hours') and not task.get('estimated_hours'):
-            task['estimated_hours'] = ex['estimated_hours']
-        # Preserve agent/branch info
-        for key in ['assigned_agent', 'branch', 'started_at', 'completed_at']:
-            if ex.get(key):
-                task[key] = ex[key]
-    merged.append(task)
-
-# Sort by priority then ID
-priority_order = {'P0': 0, 'P1': 1, 'P2': 2, 'P3': 3}
-merged.sort(key=lambda t: (priority_order.get(t.get('priority', 'P2'), 2), t.get('id', '')))
-
-# Statistics
-stats = {
-    'total': len(merged),
-    'pending': sum(1 for t in merged if t.get('status') == 'pending'),
-    'in_progress': sum(1 for t in merged if t.get('status') == 'in_progress'),
-    'completed': sum(1 for t in merged if t.get('status') == 'completed'),
-    'blocked': sum(1 for t in merged if t.get('status') == 'blocked'),
-    'cancelled': sum(1 for t in merged if t.get('status') == 'cancelled'),
-}
-
-queue = {
-    'version': '1.0.0',
-    'project': 'kenaz-dashboard',
-    'last_updated': datetime.now().isoformat(),
-    'statistics': stats,
-    'tasks': merged,
-    'metadata': {
-        'created_at': datetime.now().isoformat(),
-        'source_spec': 'dev/PRODUCT_SPEC.md',
-    }
-}
-
-os.makedirs(os.path.dirname(queue_file), exist_ok=True)
-with open(queue_file, 'w', encoding='utf-8') as f:
-    json.dump(queue, f, indent=2, ensure_ascii=False)
-
-# Output stats for shell
-print(f"TOTAL={stats['total']}")
-print(f"PENDING={stats['pending']}")
-print(f"IN_PROGRESS={stats['in_progress']}")
-print(f"COMPLETED={stats['completed']}")
-print(f"BLOCKED={stats['blocked']}")
-PYEOF
-
-if [[ "$QUIET" != "true" ]]; then
-    echo ""
-    success "Task queue synced!"
-    echo ""
-    echo "  Source:     $TASKS_DIR (completed/ is ignored)"
-    echo "  Queue file: $QUEUE_FILE"
-    echo ""
-fi

package/core/dev/specs/agent-connect/PROTOCOL.md

@@ -1,177 +0,0 @@
-# Kenaz Agent Connect — Protocol v0.4 (PROTOCOL.md)
-
-- **開發者請先讀 [`SDK_GUIDE.md`](./SDK_GUIDE.md)**——那份文件是給生態系網站開發者的接入指南（10 分鐘接入、深連結參數表、MCP 約定、審批 UX、開發模式、測試、疑難排解 toast 對照表、可跑的 `examples/minimal-site/` 範例），本檔是它背後的協定權威來源。只需要接入的讀者不需要從這裡開始讀。
-- Status: **finalized draft**, B 期（TASK_1939，2026-09-08）。取代本檔 v0.3（WebSocket relay + 配對握手協定，凍結快照在 `history/PROTOCOL_v0.3_snapshot.md`）。
-- 標準所有權：本檔是唯一權威來源。`dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` 第 2.3 節指向本檔。
-- **v0.4 的核心收斂（用戶決定，2026-09-08 晚，spec 第 6 節 Q10）：relay 整個拿掉。** 三方接口只剩兩個東西——一個 `kenaz://connect` 深連結格式、一份「網站 MCP 該長什麼樣」的最小約定。沒有 relay、沒有 WebSocket、沒有配對憑證交換、沒有線上協定訊息型別。v0.3 剩下的喚醒／憑證／狀態回報三個功能分別由深連結、網站自己簽發的一次性 token、agent 呼叫網站 MCP 得取代——見第 4 節「廢止清單」。
-- 這份文件的每個 ```json 範例都必須是**可直接 `JSON.parse` 的合法 JSON**——不可有 `|`、不可有註解、不可有多形態塞進同一個區塊。`dashboard/scripts/agent-connect-conformance/fixtures.mjs` 直接抽取這些區塊當作 conformance suite 的唯一 fixture 來源；本檔任何一個區塊解析失敗，測試就會 fail。
-
-## 0. 一句話
-
-**任何網站只要照 Kenaz 的深連結格式與 MCP 約定開發，就能用一個深連結在用戶本機喚醒 Kenaz、經用戶審批後開啟一個掛著該網站 MCP 的 Ansuz 會話；之後網站與 agent 之間的一切都走網站自己的 MCP。**
-
-三方接口：
-- **Web → Kenaz**：深連結 `kenaz://connect?site=&mcp=&token=[&prompt=][&agent=][&v=]`。用戶按下「連接」那一下（同意深連結）就是 launch 本身——沒有另外的 launch 訊息，沒有事先的配對步驟。
-- **Kenaz → Web**：沒有回程通道。網站靠 agent 呼叫它自己的 MCP 得知「連上了」（`kenaz_hello` 慣例工具，見第 2 節），逾時未呼叫就顯示「請安裝 Kenaz」。
-- **Agent ↔ Web**：只透過網站的 MCP 工具，bearer = 深連結裡的一次性 token，由網站自己簽發與驗證。
-
-明確的非目標：這不是 OAuth、不是帳號系統、不做用戶身份聯邦。「透過 Kenaz 登入 agent」的意思是把網站和本機 agent 串起來，網站不需要知道用戶是誰。
-
-## 1. 深連結格式
-
-```
-kenaz://connect?site=<url-encoded https origin>&mcp=<url-encoded https MCP url>&token=<one-time token>[&prompt=<url-encoded text>][&agent=claude|codex][&v=1]
-```
-
-| 參數 | 必填 | 說明 |
-|---|---|---|
-| `site` | 是 | 網站 origin。`https://...`；開發模式（`KENAZ_AGENT_HUB_DEV=1` 或 debug build）允許 `http://localhost` / `http://127.0.0.1` / `http://[::1]`。Kenaz 用 `Url::origin().ascii_serialization()` 正規化，去掉 path/query/fragment，作為 sites.json 的 key。 |
-| `mcp` | 是 | 網站自己的 MCP 端點，完整 URL（含 path）。scheme 規則與 `site` 相同（https；dev 模式同上放寬）。**審批卡以其 host 為主要識別**（第 3 節）——沒有 relay 就沒有「relay 驗過的 origin」，MCP URL 是 agent 真正會連的對象。 |
-| `token` | 是 | 一次性 bearer，≤512 字元，charset 限 `[A-Za-z0-9._-]`；由網站自己簽發、綁定它自己的用戶 session、自己驗證。Kenaz 不解讀、不落盤持久化——只在這次啟動的存續期間，以環境變數形式交給 agent 當 MCP 的 `Authorization: Bearer` 值。 |
-| `prompt` | 否 | 起始 prompt，交給 Ansuz 當第一則使用者訊息。**省略時由 Kenaz 自己補一句開場訊息**（純 ASCII，帶 `site` origin）觸發第一個 turn——網站不必也不應為了讓 agent 動起來而塞 `prompt=`（見第 2 節第 5 點 `kenaz_wait_for_message`）。深連結整體長度在 Windows 上約有 2 KB 限制——長內容請放在 MCP 工具裡讓 agent 自己取，不要塞進 `prompt=`。 |
-| `agent` | 否 | 指定 CLI，`"claude"` 或 `"codex"`。省略時依用戶的 dispatch 設定決定；顯式指定的 CLI 未安裝時 launch 失敗（不會靜默退回預設值）。 |
-| `v` | 否 | 協定版本，缺省 `"1"`。Kenaz 只認識自己支援的版本；不支援的版本一律 toast 拒絕（"protocol version unsupported"），不出審批卡。目前只有 `"1"`。 |
-
-任何其他/未知 query 參數（包含 v0.3 的 `relay=`）一律靜默忽略，不拒絕——只有格式不合法（scheme 錯誤、`token` 過長、`v` 不支援等）才拒絕。
-
-#### Fixture: deep_link.valid
-
-```json
-{"name": "valid", "url": "kenaz://connect?site=https://flowpix.app&mcp=https://flowpix.app/mcp&token=a1b2c3d4e5f60718293a4b5c6d7e8f90&prompt=summarize+the+canvas&agent=claude"}
-```
-
-#### Fixture: deep_link.missing_mcp
-
-```json
-{"name": "missing_mcp", "url": "kenaz://connect?site=https://flowpix.app&token=a1b2c3d4e5f60718293a4b5c6d7e8f90", "rejected_because": "missing required field: mcp"}
-```
-
-#### Fixture: deep_link.http_site_not_dev
-
-```json
-{"name": "http_site_not_dev", "url": "kenaz://connect?site=http://evil.example&mcp=https://flowpix.app/mcp&token=abc", "rejected_because": "site scheme not allowed: http (not localhost/127.0.0.1/[::1], or not in dev mode)"}
-```
-
-#### Fixture: deep_link.unsupported_version
-
-```json
-{"name": "unsupported_version", "url": "kenaz://connect?site=https://flowpix.app&mcp=https://flowpix.app/mcp&token=abc&v=999", "rejected_because": "protocol version unsupported: 999"}
-```
-
-Kenaz 收到後的完整流程：解析並驗證 → 若該 origin 已被封鎖，直接 toast 拒絕（不出審批卡）→ 否則出審批卡（第 3 節）→ 允許則在 Dashboard 開一個互動終端分頁：用戶配置的 CLI（`claude` 或 `codex`）+ Ansuz 人格（`session.js prompt Ansuz --mode=assembled --depth=elixir --no-muninn` 的輸出，逐字沿用）+ 預配 MCP（`{"mcpServers":{<name>:{"type":"http","url":<mcp>,"headers":{"Authorization":"Bearer <token>"}}}}`，`<name>` 由 `mcp` 的 hostname 衍生）+ `prompt` 作為第一則使用者訊息。cwd 永遠是 Dashboard 目前開啟的專案——網站不可指定。
-
-## 2. 網站 MCP 最小約定
-
-任何網站只要提供一個符合下列約定的 MCP 端點，就能被 Kenaz 的深連結串接：
-
-1. **驗證 bearer**：每個請求的 `Authorization: Bearer <token>` 必須被驗證是自己簽發、未過期、未撤銷的。Kenaz 不做任何驗證——這完全是網站自己的責任，也是網站唯一需要信任的邊界（Kenaz 只是把深連結裡的 token 原樣轉交給 agent）。
-1b. **`X-Kenaz-Session` header（TASK_1947，選讀）**：Kenaz 預配 MCP 時，除了 `Authorization: Bearer <token>` 之外，一律額外送一個 `X-Kenaz-Session: <launch_id>` header——`<launch_id>` 是 Kenaz 在這次啟動一開始就產生的 uuid v4（早於任何 pty 終端 session id 存在之前），同一次深連結啟動的存續期間固定不變。網站**不需要**讀這個 header 才能運作（bearer 仍是唯一必須驗證的邊界，見上一點）；它存在的目的是讓網站能分辨「這次 MCP 呼叫屬於哪一次連接」，比單純用 token 對應更直接——同一個 token 理論上可能被同一使用者的多個分頁/連接重用，但 launch_id 保證每次啟動獨一無二。codex 分支目前用 `-c mcp_servers.<name>.env_http_headers` 覆寫達到同樣效果（見下方「codex 限制」一節）；claude 分支則直接寫進預配 MCP JSON 的 `headers`。
-2. **提供 `kenaz_hello` 工具（建議）**：無參數，成功回 `{"ok": true}`。Ansuz 人格會在會話開始時、處理 `prompt` 之前呼叫一次——這是網站得知「Kenaz 真的連上了」的唯一方式（沒有回程通道，見第 0 節）。網站建議設一個逾時（建議 60 秒）：逾時未收到 `kenaz_hello` 呼叫，就顯示「請安裝 Kenaz」之類的安裝指引，而不是無限等待。
-3. **其餘工具完全由網站自訂**：Kenaz 不列舉、不審核、不限制。網站的產品邏輯（生圖、寫回、查詢……）全部經由這些自訂工具與 agent 互動，Kenaz 對這段流量完全不可見。
-4. **沒有結束通知**：agent 的終端分頁何時關閉，網站不會被告知。網站應以 token 撤銷或閒置逾時來回收狀態，不要假設有明確的「已結束」事件。
-5. **可選：`kenaz_wait_for_message`（持續對話，TASK_1948，FlowPix 分靈 2026-09-09 Feature Request S2）**：`kenaz_hello` 只解決「連上了沒」，不解決「agent 會不會一直聽網站接下來說的話」——這一點刻意不留給網站自己做 prompt 工程，而是搬進 Kenaz 人格本身：網站只要在 `tools/list` 多提供一個無參數工具 `kenaz_wait_for_message`，Ansuz 人格在呼叫過 `kenaz_hello` 並處理完 `prompt` 之後，就會反覆呼叫它。**`prompt` 省略時由 Kenaz 保證仍有一個真實的第一個 turn**（TASK_1956）——CLI 的位置參數就是互動式會話的第一則使用者訊息，空字串等於沒有第一個 turn，人格與這條約定就永遠不會被讀到；Kenaz 在 `prompt` 為空/空白時會自己補一句純 ASCII 的開場訊息（帶 `site` origin）當作這個第一則訊息，網站因此完全不需要、也不應該為了觸發第一個 turn 而自己塞一句 `prompt=`。
-   - **回傳形狀**（無參數呼叫，成功時）：
-     ```json
-     {"message": "<string|null>", "message_id": "<string|null>", "end": false}
-     ```
-     `end` 欄位可省略，省略時視為 `false`。
-   - `message` 非 `null`：agent 把它當成使用者的下一則指令執行，執行完再呼叫一次 `kenaz_wait_for_message`。
-   - `message` 為 `null`：目前沒有新訊息，不是錯誤——agent 直接再呼叫一次。
-   - `end` 為 `true`：agent 停止呼叫，告知使用者對話已結束。
-   - agent 連續呼叫這個工具失敗（逾時、拋錯、連線失敗）達 3 次，也會停止並告知使用者。
-   - 這個工具沒被列在網站的 `tools/list` 裡時，agent 完全不會呼叫它、也完全不會向使用者提起它——這段行為對沒有實作它的網站是純粹的無操作，不影響本節其餘四點的最小約定。
-   - **成本條款（強制）**：每一次 `kenaz_wait_for_message` 呼叫都是一次真實的 agent turn，成本由 Kenaz 使用者自己的訂閱額度承擔，不是網站的成本。網站**必須**用長輪詢實作——建議在伺服器端阻塞 **20-25 秒**才回傳 `message: null`，把呼叫頻率壓到最低；**不得**用短輪詢（例如每 1 秒就回一次 `null`）迫使 agent 高頻空轉，消耗使用者的訂閱額度。這是本約定唯一的強制條款，其餘都是建議。
-6. **建議標 `tool annotations`（TASK_1949，Agent Connect C-1b）**：`tools/list` 回應裡每個工具可以帶一個 `annotations` 物件（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`，MCP 規格既有欄位）。claude 分支啟動前會對你的 MCP 做一次 3 秒的 `tools/list` 探測，把 `readOnlyHint: true` 或 `destructiveHint: false` 的工具直接加進 `--allowedTools`（跳過第一次呼叫的終端機權限提示）；沒有 `annotations`、或有 `annotations` 但沒寫 `destructiveHint` 的工具，一律當成「有後果」（MCP 規格 `destructiveHint` 缺省即為 `true`），維持逐次詢問。探測本身逾時、回應非 2xx、JSON 解析失敗、或回應裡沒有 `result.tools` 陣列，一律不預先允許任何工具（不是退回全允、也不是整個 MCP 都不能用——只是每次呼叫都會跳終端機提示），並在啟動的終端第一行印出失敗原因。**未標 annotations 的工具在 claude 會逐次提問**——這不影響功能，只影響使用者要不要多按幾次終端機提示。
-
-#### Fixture: mcp.tools_list_with_annotations
-
-```json
-{"jsonrpc": "2.0", "id": 1, "result": {"tools": [{"name": "kenaz_hello", "annotations": {"destructiveHint": false, "idempotentHint": true}}, {"name": "kenaz_wait_for_message", "annotations": {"readOnlyHint": true}}, {"name": "echo", "annotations": {"readOnlyHint": true}}, {"name": "delete_all_data", "annotations": {"destructiveHint": true}}]}}
-```
-
-#### Fixture: mcp.kenaz_hello_call
-
-```json
-{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "kenaz_hello", "arguments": {}}}
-```
-
-#### Fixture: mcp.kenaz_hello_result
-
-```json
-{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "{\"ok\":true}"}], "isError": false}}
-```
-
-#### Fixture: mcp.config_with_session_header
-
-claude 分支預配的 MCP config JSON 形狀（TASK_1947）——`headers` 同時帶 `Authorization` 與 `X-Kenaz-Session`：
-
-```json
-{"mcpServers": {"flowpix": {"type": "http", "url": "https://flowpix.app/mcp", "headers": {"Authorization": "Bearer a1b2c3d4e5f60718293a4b5c6d7e8f90", "X-Kenaz-Session": "1b0d6b9a-8f2a-4c56-8abc-9f9e9c9d9e9f"}}}}
-```
-
-#### Fixture: mcp.kenaz_wait_for_message_call
-
-```json
-{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "kenaz_wait_for_message", "arguments": {}}}
-```
-
-#### Fixture: mcp.kenaz_wait_for_message_result_message
-
-```json
-{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "{\"message\":\"add a red circle to the canvas\",\"message_id\":\"m_1\",\"end\":false}"}], "isError": false}}
-```
-
-#### Fixture: mcp.kenaz_wait_for_message_result_null
-
-```json
-{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "{\"message\":null,\"message_id\":null}"}], "isError": false}}
-```
-
-## 3. 審批與權限模型
-
-不變於 v0.3：per-origin 四態權限，`unauthorized` / `once` / `always` / `blocked`，持久化在 `~/.kenaz/agent_hub/sites.json`。
-
-- `unauthorized`／`once`：每次深連結請求都出一張審批卡，內容：**site origin**、**MCP host**（主要識別——沒有 relay 驗證過的 origin，MCP 端點是 agent 真正會連的對象）、要用的 `agent`/`model`、**cwd 絕對路徑**（不可省略——網站的 prompt 完全由網站決定，用戶按允許前必須知道這次操作會在哪個資料夾發生）、`prompt` 前 120 字。用戶選擇 一次允許 / 永遠允許 / 拒絕 / 封鎖此網站。
-- `always`：跳過審批卡，直接執行（仍在本機記錄一次事件供事後稽核）。
-- `blocked`：直接拒絕，不出審批卡，只有一個本機 toast。`blocked` 也可由手動編輯 `sites.json` 達成——每次請求都重新讀檔，不信任純記憶體快取。
-- 一個被暫停的 Agent Hub（tray「Pause Agent Hub」）擋下所有深連結，包含 `always` 狀態的 origin，且不出審批卡。
-
-審批卡摘要字串格式：`"{site} → MCP {mcp_host} → {agent}/{model} · cwd {絕對路徑} · {prompt 前 120 字}"`。
-
-## 4. 廢止清單（v0.3 → v0.4，relay 全部拿掉）
-
-以下 v0.3（WebSocket relay 協定，含它收編自 Relay v1 的配對握手）曾經存在的一切，v0.4 硬切後**不再支援**。完整的歷史協定內容見 `history/PROTOCOL_v0.3_snapshot.md`；Relay v1（FlowPix）的更早歷史見 `history/README.md`。
-
-| 廢止項目 | 原用途 | 由什麼取代 |
-|---|---|---|
-| relay（整個角色，含託管 relay、`site_key`、網站註冊） | Kenaz 與網站之間的中介轉發服務 | 沒有中介——深連結直達 Kenaz，Kenaz 與網站之間再無任何直接通訊 |
-| WebSocket 連線（`ws://`/`wss://`） | relay ↔ Kenaz、relay ↔ 網站的雙向連線 | 深連結是一次性、單向、同步的請求；沒有任何持續連線 |
-| `site.hello` / `site.ready` | 網站向 relay 註冊一個 session | 不需要——網站不與 Kenaz 建立任何連線 |
-| `token.mint` / `token.minted` | 網站向 relay 請求一次性配對 token | 網站自己簽發 `token`，直接放進深連結 |
-| `pair.begin` / `pair.ok` / `pair.denied`（含 `protocol_version` 欄位） | Kenaz 向 relay 用 token 換取 `session_credential` | 深連結本身就是完整請求；`token` 直接就是 MCP bearer，不需要換發；深連結自己的 `v=` 參數取代線上版本協商 |
-| `agent.connected` / `agent.disconnected` | relay 通知網站「Kenaz 連上／斷線了」 | 網站靠 agent 呼叫 `kenaz_hello`（第 2 節）得知連上；沒有斷線通知 |
-| `agent.status`（含 `agents`/`dispatch`/`codex_logged_in`/`approval_mode`） | Kenaz 主動推送安裝/登入/審批狀態 | 沒有回程通道；審批狀態直接影響審批卡本身是否出現（第 3 節），網站不需要知道 |
-| `agent.launch`（線上訊息，含 `mcp`/`agent` 欄位） | 網站透過 relay 請求啟動一個 agent | 深連結本身就是這個請求——`mcp=`/`agent=` 是深連結參數，不是另一則訊息 |
-| `approval.pending` / `approval.resolved`（線上訊息） | Kenaz 把審批結果告知網站 | 沒有回程通道；審批只影響 Kenaz 本機是否執行 |
-| `agent.launched` / `agent.unavailable` / `agent.exited` | Kenaz 把啟動結果/結束狀態告知網站 | 沒有回程通道；網站靠 `kenaz_hello` 得知連上，之後的一切都是網站自己 MCP 工具的呼叫紀錄 |
-| 通用 `error {code, message}` | relay 對未知/廢止訊息型別的拒絕 | 深連結解析失敗直接 toast 拒絕（本機），沒有線上訊息可回 |
-| `session_credential`（`sites.json` 欄位） | relay 核發、持久化以便重連 | 深連結的 `token` 每次都由網站重新提供，不持久化、不重連 |
-| `relay_url`（`sites.json` 欄位） | 記住上次配對的 relay 端點 | 沒有 relay |
-| `mcp_url`（`sites.json` 欄位，v0.3 的「上次用過的 MCP」） | 供重連時沿用 | 深連結每次都帶 `mcp=`，不需要記住 |
-
-`sites.json` 的 origin 四態權限（`unauthorized`/`once`/`always`/`blocked`）**保留**，語意不變——見第 3 節。
-
-## codex 限制（TASK_1947 查證，codex-cli 0.153.4）
-
-- **自訂 header 支援**：codex 的 `mcp_servers.<name>` 設定支援 `env_http_headers`（header 名 → 環境變數名的對照表，值在啟動當下從環境變數讀取，同 `bearer_token_env_var` 的「值不落地在命令列/設定檔」設計）與 `http_headers`（header 名 → 字面值，直接寫死）兩種欄位——經 `codex debug models -c mcp_servers.<n>.url=... -c mcp_servers.<n>.bearer_token_env_var=... -c mcp_servers.<n>.env_http_headers={X-Kenaz-Session='<env var name>'}` 本機驗證可正常載入設定（exit 0，無錯誤）。Kenaz 因此對 codex 也送 `X-Kenaz-Session`，用 `env_http_headers` 而非 `http_headers`（維持與 bearer token 一致的「敏感/識別值只經環境變數傳遞」慣例，即使 launch_id 本身不是密鑰）。注意：`codex mcp add ... -c mcp_servers.<n>.http_headers=...`（該子指令自己的設定合併順序）會回傳 `invalid transport` 錯誤——這是 `codex mcp add` 這個子指令自己的限制，不代表 codex 整體不支援這個欄位；Kenaz 的 codex 分支走的是 `codex <prompt> -c ...` 直接呼叫，不經過 `codex mcp add`，已驗證可行。
-- **MCP 工具呼叫是否觸發審批**：codex 的 `-a/--ask-for-approval` 只列舉兩個值（`on-request` 模型自行決定何時詢問、`never` 完全不詢問），且其說明文字只提到「執行 model-generated shell 指令」——`codex mcp add --help` 也沒有任何「MCP 工具需要額外信任/審批」的旗標。查證範圍內（`--help`、`mcp add --help`、`mcp mcp --help`）沒有找到 codex 對 MCP 工具呼叫本身有獨立審批閘門的證據，也沒有找到能反面證實的方式（需要一次真的互動 session 才能實測，超出本任務 worktree 的驗證範圍——不能對正在跑的 live tauri dev 動任何東西，見本任務 worktree 規則）。**結論：未完全驗證，文件化為已知限制**——Kenaz 目前的 codex 直接呼叫（`build_interactive_script` 的 codex 分支）刻意不加 `-a never`：那會連同「shell 指令執行」的審批也一起關掉，影響範圍比「只想讓 MCP 工具別跳審批」大得多，不是這個任務該做的取捨。若之後有人在真的互動 session 裡觀察到 MCP 工具呼叫真的卡在審批提示，才是加這個旗標（或改用更窄的等效設定）的時機。
-- **annotations 分級不套用到 codex（TASK_1949 查證）**：codex `mcp_servers.<name>` 的設定欄位（`url`/`bearer_token_env_var`/`env_http_headers` 等，見上一點）裡沒有任何「只允許某些工具」或「依 tool annotations 分級」的等效設定；`codex mcp add --help`、`codex --help` 查證範圍內都沒有找到這類旗標。結論：codex 分支對 §2 point 6 的 `tools/list` annotations 完全不讀取、不探測——上一點記錄的「MCP 工具呼叫是否觸發審批」未完全驗證的結論同樣適用，codex 使用者的工具呼叫審批行為完全由 codex 自身決定，與這個任務新增的 claude-only 分級機制無關。
-
-## 5. 參考來源
-
-- `dev/specs/agent-connect/SDK_GUIDE.md`（TASK_1940，給網站開發者的接入指南——本檔的讀者導向版本）
-- `dev/KENAZ_AGENT_CONNECT_v1_SPEC.md`（v0.4，第 0、2.2、2.3、2.4、3 節是本檔的直接依據）
-- `history/PROTOCOL_v0.3_snapshot.md`（v0.3 凍結快照——WebSocket relay + 配對握手協定的完整內容）
-- `history/README.md`（Relay v1／FlowPix 更早的歷史來源）
-- 目前的 Rust 實作：`dashboard/src-tauri/src/features/agent_hub/deep_link.rs`（深連結解析）、`launch.rs`（執行）、`approval.rs`（審批卡）、`permissions.rs`（origin 四態）、`mod.rs`（串接三者）
-- 假 MCP（conformance/live-verification 用）：`dashboard/scripts/agent-hub-fake-mcp.mjs`