kenaz 0.3.21 → 0.3.23

package/core/dev/specs/agent-connect/examples/minimal-site/README.md

@@ -1,137 +0,0 @@
-# Kenaz Agent Connect — 最小範例網站
-
-`dev/specs/agent-connect/SDK_GUIDE.md` 的可跑範例。純 Node，零 npm 依賴（只用
-`node:http` / `node:crypto` / `node:fs`），可以整個資料夾複製到自己的專案外
-單獨執行，不依賴這個 repo 的其他部分。
-
-## 三行指令跑起來
-
-```bash
-cd dev/specs/agent-connect/examples/minimal-site
-node server.js
-# 瀏覽器打開 http://127.0.0.1:8420，按「連接 Kenaz」
-```
-
-（`PORT` 環境變數可以換埠；預設 8420。）
-
-## 對真 Kenaz 測試（dev 模式）
-
-Kenaz 預設只接受 `https://` 的 `site=`/`mcp=`。這個範例跑在
-`http://127.0.0.1`，所以要讓 Kenaz 完整退出（tray 選單「Quit」，不是關視
-窗）後，設定環境變數重新啟動：
-
-```bash
-KENAZ_AGENT_HUB_DEV=1 <你平常啟動 Kenaz 的方式>
-```
-
-然後按下頁面上的按鈕即可看到審批卡、終端分頁、以及本頁面輪詢到「已連線」。
-細節與常見錯誤見 `../../SDK_GUIDE.md` 的「開發模式」與「疑難排解」章節。
-
-## 不裝 Kenaz 也能測（假 Kenaz / conformance）
-
-這個範例的 MCP 端點本身就是「網站 MCP」的參考實作，可以直接用
-`dashboard/scripts/agent-connect-conformance/` 或任何會呼叫
-`kenaz_hello`/`echo` 的假 Kenaz 腳本對它跑。最小手動驗證：
-
-```bash
-node server.js &
-TOKEN=$(curl -s -X POST http://127.0.0.1:8420/api/connect | node -e \
-  'process.stdin.once("data",d=>console.log(JSON.parse(d).token))')
-curl -i -X POST http://127.0.0.1:8420/mcp \
-  -H 'content-type: application/json' \
-  -H "authorization: Bearer $TOKEN" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kenaz_hello","arguments":{}}}'
-# 期待: 200, {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"ok\":true}"}],"isError":false}}
-
-curl -i -X POST http://127.0.0.1:8420/mcp \
-  -H 'content-type: application/json' \
-  -H 'authorization: Bearer wrong-token' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kenaz_hello","arguments":{}}}'
-# 期待: 401
-```
-
-## 持續對話：`kenaz_wait_for_message`（TASK_1948）
-
-`kenaz_hello` 只解決「連上了沒」；如果你的網站想在那之後繼續跟 agent
-對話（例如使用者在你自己的聊天 UI 又打了一行字），不需要自己想 prompt
-工程——只要多提供一個無參數工具 `kenaz_wait_for_message`（見
-`../../PROTOCOL.md` 第 2 節第 5 點），Ansuz 人格會在 `kenaz_hello` 之後自
-動反覆呼叫它。這個範例把它實作成一個**記憶體信箱**，`POST /message` 投
-遞、`kenaz_wait_for_message` 長輪詢拉取：
-
-```bash
-node server.js &
-TOKEN=$(curl -s -X POST http://127.0.0.1:8420/api/connect | node -e \
-  'process.stdin.once("data",d=>console.log(JSON.parse(d).token))')
-
-# 投遞一則訊息進這個 token 的信箱
-curl -s -X POST http://127.0.0.1:8420/message \
-  -H 'content-type: application/json' \
-  -d "{\"token\":\"$TOKEN\",\"message\":\"add a red circle\"}"
-# 期待: {"ok":true,"message_id":"..."}
-
-# 拉取——已經有訊息在信箱裡，立刻回傳，不用等
-curl -i -X POST http://127.0.0.1:8420/mcp \
-  -H 'content-type: application/json' \
-  -H "authorization: Bearer $TOKEN" \
-  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kenaz_wait_for_message","arguments":{}}}'
-# 期待: 200, {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"message\":\"add a red circle\",\"message_id\":\"...\"}"}],"isError":false}}
-
-# 再拉一次——信箱空了，這次會阻塞到逾時（正式環境 20-25 秒，見 PROTOCOL.md
-# 第 2 節第 5 點的成本條款）才回 null
-curl -i -X POST http://127.0.0.1:8420/mcp \
-  -H 'content-type: application/json' \
-  -H "authorization: Bearer $TOKEN" \
-  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"kenaz_wait_for_message","arguments":{}}}'
-```
-
-`createServer({ waitTimeoutMs })` 可以覆寫預設的 20 秒逾時（`smoke.test.mjs`
-用小很多的值讓測試不用真的等）——正式網站不應該把這個值調短，短輪詢會讓
-agent 高頻空轉，消耗的是 Kenaz 使用者自己的訂閱額度，不是你的成本。
-
-## 未安裝流程（TASK_1950）
-
-按鈕的逾時邏輯不只是「等 60 秒顯示錯誤」——預設 8 秒（`KENAZ_INSTALL_
-TIMEOUT_MS` 環境變數可調）內沒收到 `kenaz_hello`，就會**主動導覽**到安
-裝頁（`KENAZ_INSTALL_URL` 環境變數，沒設時用一個明顯是佔位符的預設
-值），並把原始深連結透過 `return=` 帶過去。純函數實作在
-`public/install-redirect.js`（`hasInstallTimedOut` / `buildInstallRedirectUrl`
-/ `resolveInstallRedirect`），瀏覽器與 `test/smoke.test.mjs` 匯入同一份
-檔案。細節、時序圖、已知的假陽性取捨、`return=` 的 TTL 風險，見
-`../../SDK_GUIDE.md` 第 10 節。
-
-```bash
-KENAZ_INSTALL_URL=https://your-download-page.example KENAZ_INSTALL_TIMEOUT_MS=10000 node server.js
-```
-
-## 煙霧測試
-
-```bash
-npm test
-# 或: node --test test/smoke.test.mjs
-```
-
-起一個 OS 分配 port 的伺服器，驗證：`/api/connect` 產生合法的
-`kenaz://connect` 深連結、`/mcp` 對錯誤／缺失 bearer 回 401、合法 token 呼叫
-`kenaz_hello` 成功並反映在 `/api/status/:token`、`echo` 工具正常運作、
-`POST /message` 投遞的訊息會被 `kenaz_wait_for_message` 拉到，信箱空的時候
-會在逾時後回傳 `null`。測試結束時會關閉伺服器（`t.after(() =>
-demo.close())`），不留任何背景行程。
-
-## 檔案
-
-| 檔案 | 角色 |
-|---|---|
-| `server.js` | 四個角色合一：靜態頁、簽發 token + 組深連結的後端、網站自己的 MCP 端點（含 `kenaz_wait_for_message` 信箱）、`POST /message` 投遞入口 |
-| `public/index.html` | 「連接 Kenaz」按鈕 + 輪詢連線狀態的前端 |
-| `test/smoke.test.mjs` | `node --test` 煙霧測試 |
-| `package.json` | `"type":"module"`，零依賴 |
-
-## 這個範例刻意簡化的地方（不要照搬到正式環境）
-
-- Token 只有記憶體內的 TTL 過期，沒有真正的撤銷端點、沒有綁定使用者登入
-  session——正式網站應該把 token 綁定自己的 session 系統。
-- 沒有 HTTPS——這是為了能用 dev 模式對 `http://127.0.0.1` 測試；正式環境
-  `site=`/`mcp=` 必須是 `https://`。
-- 前端用輪詢得知「已連線」，因為 Kenaz 沒有回程通道（`SDK_GUIDE.md` 第 0
-  節）；正式網站可以換成自己的推播機制（SSE/WebSocket），原理不變。

package/core/dev/specs/agent-connect/examples/minimal-site/package.json

@@ -1,12 +0,0 @@
-{
-  "name": "kenaz-connect-minimal-site",
-  "private": true,
-  "version": "1.0.0",
-  "description": "Minimal runnable example for Kenaz Agent Connect (see ../../SDK_GUIDE.md). Zero npm dependencies.",
-  "type": "module",
-  "engines": { "node": ">=18" },
-  "scripts": {
-    "start": "node server.js",
-    "test": "node --test test/smoke.test.mjs"
-  }
-}

package/core/dev/specs/agent-connect/examples/minimal-site/public/index.html

@@ -1,116 +0,0 @@
-<!doctype html>
-<html lang="zh-Hant">
-<head>
-<meta charset="utf-8" />
-<title>Kenaz Agent Connect — Minimal Site Example</title>
-<style>
-  body { font-family: system-ui, sans-serif; max-width: 640px; margin: 48px auto; padding: 0 16px; color: #1a1a1a; }
-  button { font-size: 16px; padding: 10px 20px; cursor: pointer; }
-  #status { margin-top: 16px; padding: 12px; border-radius: 6px; background: #f2f2f2; white-space: pre-wrap; }
-  #status.connected { background: #d9f7e5; }
-  #status.error { background: #fbdede; }
-  code { background: #eee; padding: 1px 4px; border-radius: 3px; }
-</style>
-</head>
-<body>
-  <h1>Kenaz Agent Connect — Minimal Site Example</h1>
-  <p>
-    這是 <code>dev/specs/agent-connect/SDK_GUIDE.md</code> 的可跑範例。按下按鈕會：
-    (1) 向這個網站自己的後端要一個一次性 token 並組出 <code>kenaz://connect</code> 深連結，
-    (2) 導覽到那個深連結（觸發 OS 開啟 Kenaz），
-    (3) 輪詢這個網站自己的後端，等 agent 呼叫了這個網站的 <code>kenaz_hello</code> MCP 工具。
-  </p>
-  <button
-    id="connect-btn"
-    data-install-url="__KENAZ_INSTALL_URL__"
-    data-not-installed-timeout-ms="__KENAZ_INSTALL_TIMEOUT_MS__"
-  >連接 Kenaz</button>
-  <div id="status" hidden></div>
-
-  <script type="module">
-    import { resolveInstallRedirect } from './install-redirect.js';
-
-    const btn = document.getElementById('connect-btn');
-    const statusEl = document.getElementById('status');
-    // SDK_GUIDE.md §10 "未安裝流程": a short, fast-failing timeout whose
-    // ONLY job is "no kenaz_hello yet -> probably not installed, send them
-    // to the install page". Server-injected via data-* attributes (see
-    // server.js renderIndexHtml()) so this stays configurable without
-    // editing this file — real placeholder values (no known app.kenazai.com
-    // install route exists yet, see SDK_GUIDE.md §10).
-    const NOT_INSTALLED_TIMEOUT_MS = Number(btn.dataset.notInstalledTimeoutMs) || 8000;
-    const INSTALL_URL = btn.dataset.installUrl;
-    // Overall give-up point for the status text if NOT_INSTALLED_TIMEOUT_MS
-    // is disabled/misconfigured — PROTOCOL.md §2 point 2's "建議 60 秒".
-    // Normally unreachable: the shorter timeout above fires first and
-    // navigates away, ending this poll loop.
-    const HELLO_TIMEOUT_MS = 60000;
-    const POLL_INTERVAL_MS = 1000;
-
-    function showStatus(text, cls) {
-      statusEl.hidden = false;
-      statusEl.textContent = text;
-      statusEl.className = cls || '';
-    }
-
-    async function pollStatus(token, deepLink, startedAt) {
-      const res = await fetch(`/api/status/${encodeURIComponent(token)}`);
-      const data = await res.json();
-      if (data.connected) {
-        showStatus('已連線 — Kenaz 的 agent 已經呼叫了 kenaz_hello。', 'connected');
-        return;
-      }
-      const redirectUrl = resolveInstallRedirect({
-        connected: data.connected,
-        startedAt,
-        timeoutMs: NOT_INSTALLED_TIMEOUT_MS,
-        installUrl: INSTALL_URL,
-        deepLink,
-      });
-      if (redirectUrl) {
-        showStatus(
-          `${NOT_INSTALLED_TIMEOUT_MS / 1000} 秒內沒有收到 kenaz_hello — 視為尚未安裝 Kenaz，` +
-          '正在導向安裝頁…\n' + redirectUrl,
-          'error',
-        );
-        window.location.href = redirectUrl;
-        return;
-      }
-      if (Date.now() - startedAt > HELLO_TIMEOUT_MS) {
-        showStatus(
-          '逾時未收到 kenaz_hello，且未設定安裝頁導向 — 請確認已安裝 Kenaz，並且 Kenaz 在開發模式下執行（KENAZ_AGENT_HUB_DEV=1）。',
-          'error',
-        );
-        return;
-      }
-      showStatus('等待 Kenaz 連線中…（已送出深連結，等候使用者審批 + agent 呼叫 kenaz_hello）');
-      setTimeout(() => pollStatus(token, deepLink, startedAt), POLL_INTERVAL_MS);
-    }
-
-    btn.addEventListener('click', async () => {
-      btn.disabled = true;
-      showStatus('正在準備深連結…');
-      try {
-        const res = await fetch('/api/connect', {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ prompt: 'Say hello and describe what you can do on this site.' }),
-        });
-        const { deepLink, token } = await res.json();
-        showStatus('已產生深連結，正在開啟 Kenaz…\n' + deepLink);
-        // Same-tab navigation to a custom-scheme URL: the browser hands it
-        // to the OS; if nothing is registered for kenaz:// the page itself
-        // is unaffected (no navigation happens), which is why the polling
-        // + timeout below — not a navigation event — is what detects "no
-        // Kenaz installed" (SDK_GUIDE.md §10 "未安裝流程").
-        window.location.href = deepLink;
-        setTimeout(() => pollStatus(token, deepLink, Date.now()), POLL_INTERVAL_MS);
-      } catch (e) {
-        showStatus('發生錯誤：' + e.message, 'error');
-      } finally {
-        btn.disabled = false;
-      }
-    });
-  </script>
-</body>
-</html>

package/core/dev/specs/agent-connect/examples/minimal-site/public/install-redirect.js

@@ -1,73 +0,0 @@
-// "Not installed" redirect logic (TASK_1950, SDK_GUIDE.md §10 "未安裝流程").
-//
-// Framework-free ESM: no Node-only APIs (only `URL`/`URLSearchParams`/
-// `Date.now`, all global in both browsers and Node), so the exact same file
-// is imported by public/index.html (`<script type="module">`) AND by
-// test/smoke.test.mjs (`node --test`) — one implementation, not a browser
-// copy + a test-only reimplementation that could silently drift apart.
-//
-// Design: the deep link itself never tells the website "Kenaz isn't
-// installed" (SDK_GUIDE.md §0 — no return channel). The only signal is
-// silence: no kenaz_hello call within a short timeout. This module is pure
-// decision logic over that signal — it does not poll, does not touch
-// `window`, and does not navigate. The caller (index.html's poll loop)
-// supplies `connected`/`startedAt`/`now` and acts on the returned URL.
-
-/**
- * Build the URL to send an unconnected visitor to Kenaz's install page,
- * carrying the original `kenaz://connect` deep link in `return=` so the
- * install page can re-trigger the same connection attempt once Kenaz is
- * running (SDK_GUIDE.md §10).
- *
- * `installUrl` is caller-supplied on purpose — see SDK_GUIDE.md §10's
- * "安裝頁 URL 從哪裡來" note: there is no known `app.kenazai.com` install
- * route yet, so this is a configuration point, not a hardcoded guess.
- *
- * @param {string} installUrl - Kenaz's install page (or a site's own
- *   download page, or the kenaz-release bucket's latest.json consumer).
- * @param {string} deepLink - the original `kenaz://connect?...` URL that
- *   timed out.
- * @returns {string} `installUrl` with a `return` query param added.
- */
-export function buildInstallRedirectUrl(installUrl, deepLink) {
-  const url = new URL(installUrl);
-  url.searchParams.set('return', deepLink);
-  return url.toString();
-}
-
-/**
- * Has the "not installed" timeout elapsed without a `kenaz_hello`?
- * Pure — takes `now` explicitly instead of reading `Date.now()` itself, so
- * callers (and tests) can reason about it without a real sleep.
- *
- * @param {{ startedAt: number, timeoutMs: number, now?: number }} args
- * @returns {boolean}
- */
-export function hasInstallTimedOut({ startedAt, timeoutMs, now = Date.now() }) {
-  return now - startedAt >= timeoutMs;
-}
-
-/**
- * Single decision point for the poll loop: given the current connection
- * state and elapsed time, either "not yet" (`null`) or the install-page URL
- * to navigate to right now.
- *
- * Never redirects once `connected` is true, even past the timeout — a slow
- * network hop delivering the status response after Kenaz already called
- * `kenaz_hello` must not still bounce the visitor to the install page.
- *
- * @param {{
- *   connected: boolean,
- *   startedAt: number,
- *   timeoutMs: number,
- *   installUrl: string,
- *   deepLink: string,
- *   now?: number,
- * }} args
- * @returns {string|null}
- */
-export function resolveInstallRedirect({ connected, startedAt, timeoutMs, installUrl, deepLink, now = Date.now() }) {
-  if (connected) return null;
-  if (!hasInstallTimedOut({ startedAt, timeoutMs, now })) return null;
-  return buildInstallRedirectUrl(installUrl, deepLink);
-}