kenaz 0.3.21 → 0.3.23

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

@@ -1,516 +0,0 @@
-#!/usr/bin/env node
-// Kenaz Agent Connect — minimal example website (TASK_1940).
-//
-// This is the reference implementation SDK_GUIDE.md points readers at: one
-// Node process, ZERO npm dependencies (node:http/node:crypto/node:fs only —
-// deliberately not importing dashboard/scripts/agent-hub-fake-mcp.mjs even
-// though that file has no external deps either, so this example stays
-// copy-pasteable on its own, outside this repo, without dragging along the
-// rest of KenazAI). It plays all three roles a real integration splits
-// across a frontend + backend:
-//   1. GET  /          — the page with the "連接 Kenaz" button (public/index.html)
-//   2. POST /api/connect  — mints a one-time token, returns a kenaz://connect
-//      deep link (PROTOCOL.md §1) — this is "the website's backend"
-//   3. GET  /api/status/:token — the frontend polls this to learn whether
-//      the agent has called kenaz_hello yet (there is no push channel —
-//      PROTOCOL.md §0: "Kenaz → Web：沒有回程通道")
-//   4. POST /mcp        — the website's own MCP endpoint (PROTOCOL.md §2):
-//      bearer-checks every request, exposes `kenaz_hello` (no-arg, records
-//      the call so /api/status can report it), `kenaz_wait_for_message`
-//      (TASK_1948, PROTOCOL.md §2 point 5 — long-polls a per-token mailbox
-//      so the Ansuz persona can keep listening for this site's next
-//      instruction after kenaz_hello), and one demo tool `echo`.
-//   5. POST /message    — delivers a message into a token's mailbox (not
-//      part of PROTOCOL.md itself — that only specifies the MCP tool's
-//      shape; this is this demo's stand-in for "however a real site's own
-//      chat UI / webhook hands the agent its next instruction").
-//
-// Run: node server.js  (see README.md for the two follow-up steps)
-
-import http from 'node:http';
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-// ── Token store ──────────────────────────────────────────────────────────
-// One-time per "連接" click (PROTOCOL.md §1 `token`): minted fresh here,
-// never reused across two different connect attempts. TTL-bound so a stale
-// token from an abandoned attempt stops working on its own — this is the
-// "撤銷建議" SDK_GUIDE.md's security section talks about; a real backend
-// would also expose an explicit revoke path (DELETE /api/connect/:token or
-// similar) and bind the token to the visitor's own login session, neither
-// of which this demo has a session system to hang off.
-const TOKEN_TTL_MS = 10 * 60 * 1000; // 10 minutes
-
-// ── "Not installed" redirect config (TASK_1950, SDK_GUIDE.md §10) ───────
-// No known app.kenazai.com install route exists yet — this is deliberately
-// a placeholder, configurable via env var rather than a guessed URL (see
-// SDK_GUIDE.md §10 "安裝頁 URL 從哪裡來"). A real site should point this at
-// its own download page, or a page that reads the kenaz-release bucket's
-// latest.json (see dashboard/scripts/publish-release.js) and redirects to
-// the per-platform installer URL in it.
-const DEFAULT_INSTALL_URL = process.env.KENAZ_INSTALL_URL || 'https://kenaz-install.example/placeholder';
-// SDK_GUIDE.md §10 default: 8 seconds. Overridable so this demo (and anyone
-// forking it) can tune the not-installed/still-approving tradeoff without
-// editing public/index.html.
-const DEFAULT_INSTALL_TIMEOUT_MS = Number(process.env.KENAZ_INSTALL_TIMEOUT_MS || 8000);
-
-// Default kenaz_wait_for_message long-poll window (PROTOCOL.md §2 point 5's
-// "建議在伺服器端阻塞 20-25 秒才回傳 message: null" — the low end of that
-// range). Overridable via createServer({ waitTimeoutMs }) — the smoke test
-// and the conformance suite pass small values so they don't have to sit
-// through a real 20s wait.
-const DEFAULT_WAIT_TIMEOUT_MS = 20 * 1000;
-
-/** @type {Map<string, { createdAt: number, helloCalledAt: number|null }>} */
-const tokens = new Map();
-
-function mintToken() {
-  // base64url charset (A-Za-z0-9-_) is a strict subset of deep_link.rs's
-  // allowed token charset ([A-Za-z0-9._-]) — see PROTOCOL.md §1's token row.
-  const token = crypto.randomBytes(24).toString('base64url');
-  tokens.set(token, { createdAt: Date.now(), helloCalledAt: null });
-  return token;
-}
-
-function getValidToken(token) {
-  const entry = tokens.get(token);
-  if (!entry) return null;
-  if (Date.now() - entry.createdAt > TOKEN_TTL_MS) {
-    tokens.delete(token);
-    return null;
-  }
-  return entry;
-}
-
-// Sweep expired tokens periodically so the demo doesn't leak memory across a
-// long-running process. unref() so it never keeps the process alive on its
-// own (matters for the smoke test's server.close()).
-setInterval(() => {
-  const now = Date.now();
-  for (const [token, entry] of tokens) {
-    if (now - entry.createdAt > TOKEN_TTL_MS) tokens.delete(token);
-  }
-}, 60 * 1000).unref();
-
-// ── Mailbox: kenaz_wait_for_message (PROTOCOL.md §2 point 5, TASK_1948) ──
-// One mailbox per token: a FIFO queue of undelivered messages, plus a list
-// of long-poll waiters (agent calls currently blocked in kenaz_wait_for_
-// message with nothing queued yet). POST /message either hands a fresh
-// message straight to the oldest waiting long-poll call, or — if nobody is
-// waiting right now — queues it for the next call. This is the website side
-// of the "agent keeps listening" convention: a real site would deliver here
-// from its own chat UI / webhook instead of a bare POST.
-
-/** @type {Map<string, { queue: Array<{message: string, message_id: string}>, waiters: Array<(v: {message: string|null, message_id: string|null}) => void> }>} */
-const mailboxes = new Map();
-
-function getMailbox(token) {
-  let mb = mailboxes.get(token);
-  if (!mb) {
-    mb = { queue: [], waiters: [] };
-    mailboxes.set(token, mb);
-  }
-  return mb;
-}
-
-/** Deliver a message into `token`'s mailbox. Returns the minted message_id. */
-function deliverMessage(token, message) {
-  const mb = getMailbox(token);
-  const message_id = crypto.randomUUID();
-  const waiter = mb.waiters.shift();
-  if (waiter) {
-    waiter({ message, message_id });
-  } else {
-    mb.queue.push({ message, message_id });
-  }
-  return message_id;
-}
-
-/**
- * The kenaz_wait_for_message long-poll itself: resolves immediately if a
- * message is already queued, otherwise blocks up to `timeoutMs` and
- * resolves `{message: null, message_id: null}` if nothing arrives in time
- * (PROTOCOL.md §2 point 5's "message 為 null" case — not an error).
- * `timeoutMs` defaults to the spec's 20s floor; the smoke test and
- * conformance suite override it to a small value so they don't have to
- * actually sit through a real long-poll window.
- */
-function waitForMessage(token, timeoutMs) {
-  const mb = getMailbox(token);
-  const queued = mb.queue.shift();
-  if (queued) return Promise.resolve(queued);
-
-  return new Promise((resolve) => {
-    let settled = false;
-    const resolveOnce = (value) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(value);
-    };
-    const timer = setTimeout(() => {
-      const idx = mb.waiters.indexOf(resolveOnce);
-      if (idx !== -1) mb.waiters.splice(idx, 1);
-      resolveOnce({ message: null, message_id: null });
-    }, timeoutMs);
-    timer.unref();
-    mb.waiters.push(resolveOnce);
-  });
-}
-
-// ── kenaz://connect deep link builder (PROTOCOL.md §1) ──────────────────
-
-function buildConnectUrl({ site, mcp, token, prompt, agent, v }) {
-  const params = new URLSearchParams();
-  params.set('site', site);
-  params.set('mcp', mcp);
-  params.set('token', token);
-  if (prompt) params.set('prompt', prompt);
-  if (agent) params.set('agent', agent);
-  if (v) params.set('v', v);
-  return `kenaz://connect?${params.toString()}`;
-}
-
-// ── MCP JSON-RPC (PROTOCOL.md §2 — the website's own MCP) ───────────────
-// Same "Streamable HTTP" shape as dashboard/scripts/agent-hub-fake-mcp.mjs
-// (single application/json body per POST, no SSE — this demo never streams
-// anything) because that is the transport claude's `--mcp-config`
-// `"type":"http"` / codex's `-c mcp_servers.*` overrides actually speak.
-
-function jsonRpcResult(id, result) {
-  return { jsonrpc: '2.0', id, result };
-}
-function jsonRpcError(id, code, message) {
-  return { jsonrpc: '2.0', id: id ?? null, error: { code, message } };
-}
-
-async function handleMcpRpc(msg, { onKenazHello, token, waitTimeoutMs } = {}) {
-  if (!msg || msg.jsonrpc !== '2.0') {
-    return jsonRpcError(msg && msg.id, -32600, 'Invalid Request — expected jsonrpc:"2.0"');
-  }
-  switch (msg.method) {
-    case 'initialize':
-      return jsonRpcResult(msg.id, {
-        protocolVersion: '2025-06-18',
-        capabilities: { tools: {} },
-        serverInfo: { name: 'kenaz-connect-minimal-site', version: '1.0.0' },
-      });
-    case 'notifications/initialized':
-      return null; // notification — no response body
-    case 'tools/list':
-      return jsonRpcResult(msg.id, {
-        tools: [
-          {
-            name: 'kenaz_hello',
-            description: 'No-arg tool the Ansuz persona calls once at session start (PROTOCOL.md §2).',
-            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-            // TASK_1949 (Agent Connect C-1b, PROTOCOL.md §2 point 6): a
-            // no-op notification, not destructive, and safe to call more
-            // than once — kenaz's claude branch pre-allows it via
-            // --allowedTools so the FIRST tool call of the session doesn't
-            // also stop for a terminal permission prompt.
-            annotations: { destructiveHint: false, idempotentHint: true },
-          },
-          {
-            name: 'kenaz_wait_for_message',
-            description:
-              'No-arg, optional (PROTOCOL.md §2 point 5). Long-polls this token\'s mailbox and ' +
-              'returns {message, message_id, end} — the Ansuz persona calls this repeatedly ' +
-              'after kenaz_hello to keep listening for the next instruction from this site.',
-            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-            // Pure read of the mailbox — never mutates anything server-side.
-            annotations: { readOnlyHint: true },
-          },
-          {
-            name: 'echo',
-            description: 'Demo tool — echoes back whatever "text" argument it was given.',
-            inputSchema: {
-              type: 'object',
-              properties: { text: { type: 'string' } },
-              additionalProperties: false,
-            },
-            // Echoing back input has no side effect.
-            annotations: { readOnlyHint: true },
-          },
-        ],
-      });
-    case 'tools/call': {
-      const toolName = msg.params && msg.params.name;
-      if (toolName === 'kenaz_hello') {
-        if (typeof onKenazHello === 'function') onKenazHello();
-        return jsonRpcResult(msg.id, {
-          content: [{ type: 'text', text: JSON.stringify({ ok: true }) }],
-          isError: false,
-        });
-      }
-      if (toolName === 'kenaz_wait_for_message') {
-        const { message, message_id } = await waitForMessage(token, waitTimeoutMs);
-        return jsonRpcResult(msg.id, {
-          content: [{ type: 'text', text: JSON.stringify({ message, message_id }) }],
-          isError: false,
-        });
-      }
-      if (toolName === 'echo') {
-        const text = (msg.params && msg.params.arguments && msg.params.arguments.text) || '';
-        return jsonRpcResult(msg.id, {
-          content: [{ type: 'text', text: JSON.stringify({ echo: text }) }],
-          isError: false,
-        });
-      }
-      return jsonRpcError(msg.id, -32602, `Unknown tool: ${JSON.stringify(toolName)}`);
-    }
-    default:
-      if (msg.id === undefined) return null;
-      return jsonRpcError(msg.id, -32601, `Method not found: ${msg.method}`);
-  }
-}
-
-async function handleMcpRequest(req, res, body, { waitTimeoutMs = DEFAULT_WAIT_TIMEOUT_MS } = {}) {
-  const authHeader = req.headers['authorization'] || null;
-  const expected = authHeader && authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null;
-  const entry = expected ? getValidToken(expected) : null;
-
-  if (!entry) {
-    // AC: "範例網站的 MCP 對錯誤 bearer 回 401（對照組）" — this is the
-    // ONLY auth check the whole example has; Kenaz itself never validates
-    // the token (PROTOCOL.md §2 point 1 — "Kenaz 不做任何驗證").
-    res.writeHead(401, { 'content-type': 'application/json' });
-    res.end(JSON.stringify({ error: 'unauthorized' }));
-    return;
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(body || '{}');
-  } catch (e) {
-    res.writeHead(400, { 'content-type': 'application/json' });
-    res.end(JSON.stringify(jsonRpcError(null, -32700, `Parse error: ${e.message}`)));
-    return;
-  }
-
-  const onKenazHello = () => {
-    entry.helloCalledAt = Date.now();
-  };
-
-  const messages = Array.isArray(parsed) ? parsed : [parsed];
-  const responses = (
-    await Promise.all(messages.map((m) => handleMcpRpc(m, { onKenazHello, token: expected, waitTimeoutMs })))
-  ).filter((r) => r !== null);
-
-  if (!req.headers['mcp-session-id']) {
-    res.setHeader('Mcp-Session-Id', crypto.randomUUID());
-  } else {
-    res.setHeader('Mcp-Session-Id', req.headers['mcp-session-id']);
-  }
-
-  if (responses.length === 0) {
-    res.writeHead(202);
-    res.end();
-    return;
-  }
-
-  res.writeHead(200, { 'content-type': 'application/json' });
-  res.end(JSON.stringify(Array.isArray(parsed) ? responses : responses[0]));
-}
-
-// ── HTTP app ──────────────────────────────────────────────────────────────
-
-/**
- * Inject the configured install-page URL + not-installed timeout into
- * public/index.html's `data-*` attributes (TASK_1950). Plain string
- * substitution — no templating engine needed for two placeholders, and
- * pulling one in would be the wrong end of the YAGNI ladder for a
- * zero-dependency demo (see server.js's file-header comment).
- */
-function renderIndexHtml({ installUrl, installTimeoutMs }) {
-  const html = fs.readFileSync(path.join(__dirname, 'public', 'index.html'), 'utf8');
-  return html
-    .replace('__KENAZ_INSTALL_URL__', installUrl)
-    .replace('__KENAZ_INSTALL_TIMEOUT_MS__', String(installTimeoutMs));
-}
-
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    req.on('data', (c) => chunks.push(c));
-    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
-    req.on('error', reject);
-  });
-}
-
-/**
- * Build the HTTP request handler. `baseUrl` (e.g. "http://127.0.0.1:8420")
- * is injected rather than read from `req` so the deep link's `site=`/`mcp=`
- * always match whatever origin the browser actually loaded the page from —
- * see createServer() below.
- */
-export function createRequestListener(
-  getBaseUrl,
-  {
-    waitTimeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
-    installUrl = DEFAULT_INSTALL_URL,
-    installTimeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
-  } = {},
-) {
-  return async (req, res) => {
-    const url = new URL(req.url, 'http://internal');
-
-    if (req.method === 'GET' && url.pathname === '/install-redirect.js') {
-      // Served as a real static file (not inlined into index.html) so the
-      // exact same module test/smoke.test.mjs imports is what the browser
-      // runs — see install-redirect.js's file-header comment.
-      const js = fs.readFileSync(path.join(__dirname, 'public', 'install-redirect.js'), 'utf8');
-      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' });
-      res.end(js);
-      return;
-    }
-
-    if (req.method === 'POST' && url.pathname === '/message') {
-      // Deliver a message into a token's mailbox (TASK_1948) — stands in for
-      // whatever real trigger a production site would use (its own chat UI,
-      // a webhook, a queue consumer...) to hand the agent its next
-      // instruction via kenaz_wait_for_message. Not part of PROTOCOL.md
-      // itself — that only specifies the MCP tool's shape, not how a
-      // website gets a message INTO its own backend in the first place.
-      const body = await readBody(req);
-      let payload;
-      try {
-        payload = JSON.parse(body || '{}');
-      } catch (e) {
-        res.writeHead(400, { 'content-type': 'application/json' });
-        res.end(JSON.stringify({ error: `invalid JSON body: ${e.message}` }));
-        return;
-      }
-      const { token, message } = payload;
-      const entry = typeof token === 'string' ? getValidToken(token) : null;
-      if (!entry) {
-        res.writeHead(404, { 'content-type': 'application/json' });
-        res.end(JSON.stringify({ error: 'unknown or expired token' }));
-        return;
-      }
-      if (typeof message !== 'string' || message.length === 0) {
-        res.writeHead(400, { 'content-type': 'application/json' });
-        res.end(JSON.stringify({ error: 'message must be a non-empty string' }));
-        return;
-      }
-      const message_id = deliverMessage(token, message);
-      res.writeHead(200, { 'content-type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, message_id }));
-      return;
-    }
-
-    if (req.method === 'GET' && url.pathname === '/') {
-      const html = renderIndexHtml({ installUrl, installTimeoutMs });
-      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-      res.end(html);
-      return;
-    }
-
-    if (req.method === 'POST' && url.pathname === '/api/connect') {
-      const body = await readBody(req);
-      let prompt = '';
-      try {
-        prompt = JSON.parse(body || '{}').prompt || '';
-      } catch {
-        // ignore — empty prompt is a valid, documented case (PROTOCOL.md §1)
-      }
-      const token = mintToken();
-      const base = getBaseUrl();
-      const deepLink = buildConnectUrl({
-        site: base,
-        mcp: `${base}/mcp`,
-        token,
-        prompt,
-      });
-      res.writeHead(200, { 'content-type': 'application/json' });
-      res.end(JSON.stringify({ deepLink, token }));
-      return;
-    }
-
-    if (req.method === 'GET' && url.pathname.startsWith('/api/status/')) {
-      const token = url.pathname.slice('/api/status/'.length);
-      const entry = getValidToken(token);
-      res.writeHead(200, { 'content-type': 'application/json' });
-      res.end(
-        JSON.stringify({
-          known: !!entry,
-          connected: !!(entry && entry.helloCalledAt),
-          calledAt: entry ? entry.helloCalledAt : null,
-        }),
-      );
-      return;
-    }
-
-    if (url.pathname === '/mcp') {
-      if (req.method === 'GET') {
-        res.writeHead(200, { 'content-type': 'text/plain' });
-        res.end('kenaz-connect-minimal-site MCP: POST JSON-RPC here\n');
-        return;
-      }
-      if (req.method === 'POST') {
-        const body = await readBody(req);
-        await handleMcpRequest(req, res, body, { waitTimeoutMs });
-        return;
-      }
-      res.writeHead(405, { 'content-type': 'application/json' });
-      res.end(JSON.stringify({ error: 'method not allowed' }));
-      return;
-    }
-
-    res.writeHead(404, { 'content-type': 'application/json' });
-    res.end(JSON.stringify({ error: 'not found' }));
-  };
-}
-
-/**
- * Start the demo server on `port` (0 = OS-assigned, used by the smoke test).
- * Returns { server, port, close }.
- */
-export function createServer({
-  port = 0,
-  host = '127.0.0.1',
-  waitTimeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
-  installUrl = DEFAULT_INSTALL_URL,
-  installTimeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
-} = {}) {
-  let baseUrl = `http://${host}:${port}`;
-  const server = http.createServer(
-    createRequestListener(() => baseUrl, { waitTimeoutMs, installUrl, installTimeoutMs }),
-  );
-  return {
-    server,
-    async listen() {
-      await new Promise((resolve) => server.listen(port, host, resolve));
-      const actualPort = server.address().port;
-      baseUrl = `http://${host}:${actualPort}`;
-      return actualPort;
-    },
-    get baseUrl() {
-      return baseUrl;
-    },
-    close() {
-      return new Promise((resolve) => server.close(() => resolve()));
-    },
-  };
-}
-
-async function runCli() {
-  const requestedPort = Number(process.env.PORT || 8420);
-  const demo = createServer({ port: requestedPort });
-  const actualPort = await demo.listen();
-  console.log(`[minimal-site] listening on ${demo.baseUrl}`);
-  console.log(`[minimal-site] open ${demo.baseUrl} in a browser to try "連接 Kenaz"`);
-  console.log('[minimal-site] MCP endpoint (bearer-protected): ' + demo.baseUrl + '/mcp');
-  if (actualPort !== requestedPort) {
-    console.log(`[minimal-site] note: requested port ${requestedPort} was busy, using ${actualPort} instead`);
-  }
-}
-
-const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
-if (isMain) {
-  runCli();
-}