kenaz 0.0.0-stage → 0.3.2

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

@@ -0,0 +1,516 @@
+#!/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();
+}