kiku-agent 1.3.0 → 1.3.1

package/server/agent/websearch/security/ssrf.js

@@ -0,0 +1,289 @@
+import http from 'node:http';
+import https from 'node:https';
+import { lookup as dnsLookup } from 'node:dns/promises';
+
+export function parseIPv4(host) {
+  if (typeof host !== 'string' || !host) return null;
+  if (host.includes(':')) return null;
+
+  const parts = host.split('.');
+  if (parts.length > 4 || parts.length === 0) return null;
+
+  const numbers = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!part) return null;
+    let val;
+    if (/^0x[0-9a-f]+$/i.test(part)) {
+      val = parseInt(part, 16);
+    } else if (/^0[0-7]+$/.test(part)) {
+      val = parseInt(part, 8);
+    } else if (/^\d+$/.test(part)) {
+      val = parseInt(part, 10);
+    } else {
+      return null;
+    }
+    if (isNaN(val) || val < 0) return null;
+    numbers.push(val);
+  }
+
+  let a, b, c, d;
+  if (numbers.length === 1) {
+    const n = numbers[0];
+    if (n > 0xffffffff) return null;
+    a = (n >>> 24) & 255;
+    b = (n >>> 16) & 255;
+    c = (n >>> 8) & 255;
+    d = n & 255;
+  } else if (numbers.length === 2) {
+    if (numbers[0] > 255 || numbers[1] > 0xffffff) return null;
+    a = numbers[0];
+    b = (numbers[1] >>> 16) & 255;
+    c = (numbers[1] >>> 8) & 255;
+    d = numbers[1] & 255;
+  } else if (numbers.length === 3) {
+    if (numbers[0] > 255 || numbers[1] > 255 || numbers[2] > 0xffff) return null;
+    a = numbers[0];
+    b = numbers[1];
+    c = (numbers[2] >>> 8) & 255;
+    d = numbers[2] & 255;
+  } else if (numbers.length === 4) {
+    if (numbers.some(n => n > 255)) return null;
+    [a, b, c, d] = numbers;
+  } else {
+    return null;
+  }
+
+  return `${a}.${b}.${c}.${d}`;
+}
+
+export function isPrivateIPv4(ip) {
+  const parsed = parseIPv4(ip) || (typeof ip === 'string' ? ip : '');
+  const parts = parsed.split('.').map(Number);
+  if (parts.length !== 4 || parts.some(p => isNaN(p) || p < 0 || p > 255)) return false;
+
+  if (parts[0] === 127) return true;
+  if (parts[0] === 10) return true;
+  if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+  if (parts[0] === 192 && parts[1] === 168) return true;
+  if (parts[0] === 169 && parts[1] === 254) return true;
+  if (parts[0] === 0) return true;
+  if (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127) return true;
+  if (parts[0] === 198 && (parts[1] === 18 || parts[1] === 19)) return true;
+  if (parts[0] >= 224) return true;
+
+  return false;
+}
+
+export function isPrivateIPv6(ip) {
+  const clean = ip.toLowerCase().trim();
+  
+  if (clean === '::1' || clean === '0:0:0:0:0:0:0:1' || clean === '::') return true;
+  
+  if (/^fe[89ab]/i.test(clean)) return true;
+  
+  if (/^f[cd]/i.test(clean)) return true;
+
+  const mapped = clean.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped && isPrivateIPv4(mapped[1])) return true;
+
+  return false;
+}
+
+export function isIpAddress(host) {
+  if (!host || typeof host !== 'string') return false;
+  return Boolean(parseIPv4(host)) || host.includes(':');
+}
+
+const DNS_CACHE = new Map();
+const DNS_CACHE_TTL_MS = 60_000;
+const DNS_CACHE_FAIL_TTL_MS = 10_000;
+const DNS_CACHE_MAX_ENTRIES = 1000;
+
+function setDnsCacheEntry(hostname, entry) {
+  if (!DNS_CACHE.has(hostname) && DNS_CACHE.size >= DNS_CACHE_MAX_ENTRIES) {
+    const oldestKey = DNS_CACHE.keys().next().value;
+    if (oldestKey !== undefined) DNS_CACHE.delete(oldestKey);
+  }
+  DNS_CACHE.set(hostname, entry);
+}
+
+export function clearDnsCache() {
+  DNS_CACHE.clear();
+}
+
+const httpKeepAliveAgent = new http.Agent({ keepAlive: true, maxSockets: 20 });
+const httpsKeepAliveAgent = new https.Agent({ keepAlive: true, maxSockets: 20 });
+
+export async function assertSafeUrlHostname(hostname) {
+  if (!hostname || typeof hostname !== 'string') {
+    return { safe: false, reason: 'Missing hostname' };
+  }
+  const clean = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();
+
+  if (clean === 'localhost' || clean.endsWith('.localhost') || clean.includes('metadata.google') || clean.includes('169.254.169.254')) {
+    return { safe: false, reason: `Blocked hostname: ${clean}` };
+  }
+
+  const parsedIp = parseIPv4(clean);
+  if (parsedIp) {
+    if (isPrivateIPv4(parsedIp)) {
+      return { safe: false, reason: `Target is private/internal IP: ${clean}` };
+    }
+    return { safe: true, pinnedIp: parsedIp };
+  }
+
+  if (isIpAddress(clean)) {
+    if (isPrivateIPv6(clean)) {
+      return { safe: false, reason: `Target is private/internal IP: ${clean}` };
+    }
+    return { safe: true, pinnedIp: clean };
+  }
+
+  const cached = DNS_CACHE.get(clean);
+  if (cached && cached.expiresAt > Date.now()) {
+    return { safe: cached.safe, pinnedIp: cached.pinnedIp, reason: cached.reason };
+  }
+
+  try {
+    const addresses = await dnsLookup(clean, { all: true });
+    if (!addresses || addresses.length === 0) {
+      const res = { safe: false, reason: `Unable to resolve DNS for hostname "${clean}"` };
+      setDnsCacheEntry(clean, { ...res, expiresAt: Date.now() + DNS_CACHE_FAIL_TTL_MS });
+      return res;
+    }
+
+    for (const { address } of addresses) {
+      if (isPrivateIPv4(address) || isPrivateIPv6(address)) {
+        const res = { safe: false, reason: `Hostname "${clean}" resolved to private IP: ${address}` };
+        setDnsCacheEntry(clean, { ...res, expiresAt: Date.now() + DNS_CACHE_FAIL_TTL_MS });
+        return res;
+      }
+    }
+
+    const res = { safe: true, pinnedIp: addresses[0].address };
+    setDnsCacheEntry(clean, { ...res, expiresAt: Date.now() + DNS_CACHE_TTL_MS });
+    return res;
+  } catch (err) {
+    const res = { safe: false, reason: `DNS lookup failed for "${clean}": ${err.message}` };
+    setDnsCacheEntry(clean, { ...res, expiresAt: Date.now() + DNS_CACHE_FAIL_TTL_MS });
+    return res;
+  }
+}
+
+
+export async function safeFetchWithPinning(inputUrl, options = {}, maxRedirects = 3) {
+  let currentUrl = String(inputUrl || '');
+  let currentOptions = { ...options };
+
+  for (let redirects = 0; redirects <= maxRedirects; redirects++) {
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(currentUrl);
+    } catch {
+      throw new Error(`Invalid URL format: "${currentUrl}"`);
+    }
+
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+      throw new Error(`Unsupported protocol: ${parsedUrl.protocol}`);
+    }
+
+    const hostname = parsedUrl.hostname.toLowerCase();
+    const ssrfCheck = await assertSafeUrlHostname(hostname);
+    if (!ssrfCheck.safe) {
+      throw new Error(`SSRF Guard rejected: ${ssrfCheck.reason}`);
+    }
+
+    const targetIp = ssrfCheck.pinnedIp;
+    const isHttps = parsedUrl.protocol === 'https:';
+    const client = isHttps ? https : http;
+    const port = parsedUrl.port ? Number(parsedUrl.port) : (isHttps ? 443 : 80);
+    const method = String(currentOptions.method || 'GET').toUpperCase();
+
+    const headers = { ...(currentOptions.headers || {}) };
+    if (!headers.host && !headers.Host) {
+      headers.Host = parsedUrl.host;
+    }
+
+    const agent = currentOptions.agent || (isHttps ? httpsKeepAliveAgent : httpKeepAliveAgent);
+
+    const response = await new Promise((resolve, reject) => {
+      let req = null;
+      try {
+        req = client.request({
+          host: targetIp, 
+          port,
+          path: parsedUrl.pathname + parsedUrl.search,
+          method,
+          headers,
+          agent,
+          servername: isHttps ? hostname : undefined, 
+          signal: currentOptions.signal,
+          timeout: currentOptions.timeoutMs || 15000
+        }, res => {
+          const chunks = [];
+          let bytesReceived = 0;
+          const maxBytes = currentOptions.maxBytes || 5_000_000;
+
+          res.on('data', chunk => {
+            bytesReceived += chunk.length;
+            if (bytesReceived <= maxBytes) {
+              chunks.push(chunk);
+            } else {
+              res.destroy();
+              req.destroy();
+            }
+          });
+
+          res.on('end', () => {
+            const bodyBuffer = Buffer.concat(chunks);
+            const responseHeaders = new Headers();
+            for (const [k, v] of Object.entries(res.headers)) {
+              if (Array.isArray(v)) {
+                v.forEach(val => responseHeaders.append(k, val));
+              } else if (v !== undefined) {
+                responseHeaders.set(k, v);
+              }
+            }
+
+            resolve({
+              status: res.statusCode || 200,
+              statusText: res.statusMessage || '',
+              ok: res.statusCode >= 200 && res.statusCode < 300,
+              headers: responseHeaders,
+              url: parsedUrl.href,
+              text: async () => bodyBuffer.toString('utf8'),
+              json: async () => JSON.parse(bodyBuffer.toString('utf8')),
+              buffer: async () => bodyBuffer
+            });
+          });
+        });
+
+        req.on('error', reject);
+        req.on('timeout', () => {
+          req.destroy(new Error(`Request to ${hostname} (${targetIp}) timed out`));
+        });
+
+        if (currentOptions.body) {
+          req.write(currentOptions.body);
+        }
+        req.end();
+      } catch (err) {
+        reject(err);
+      }
+    });
+
+    const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+    if (!REDIRECT_STATUSES.has(response.status)) {
+      return response;
+    }
+
+    const location = response.headers.get('location');
+    if (!location) return response;
+    if (redirects === maxRedirects) throw new Error('Too many redirects');
+
+    currentUrl = new URL(location, parsedUrl).href;
+  }
+
+  throw new Error('Too many redirects');
+}

package/server/agent/websearch/telemetry.js

@@ -0,0 +1,71 @@
+export class SearchTelemetry {
+  constructor() {
+    this.reset();
+  }
+
+  reset() {
+    this.totalSearches = 0;
+    this.fallbackTriggers = 0;
+    this.zeroResults = 0;
+    this.latencies = [];
+    this.circuitBreakerTrips = {
+      duckduckgo: 0,
+      searxng: 0,
+      jina: 0
+    };
+    this.searchesByEngine = {
+      duckduckgo: 0,
+      searxng: 0,
+      jina: 0
+    };
+  }
+
+  recordSearch({ latencyMs = 0, fallbackOccurred = false, zeroResult = false, engine = null } = {}) {
+    this.totalSearches++;
+    if (fallbackOccurred) this.fallbackTriggers++;
+    if (zeroResult) this.zeroResults++;
+    if (Number.isFinite(latencyMs) && latencyMs >= 0) {
+      this.latencies.push(latencyMs);
+      if (this.latencies.length > 2000) {
+        this.latencies = this.latencies.slice(-1000);
+      }
+    }
+    if (engine && this.searchesByEngine[engine] !== undefined) {
+      this.searchesByEngine[engine]++;
+    }
+  }
+
+  recordCircuitTrip(engine) {
+    const key = String(engine || '').toLowerCase();
+    if (this.circuitBreakerTrips[key] !== undefined) {
+      this.circuitBreakerTrips[key]++;
+    } else {
+      this.circuitBreakerTrips[key] = 1;
+    }
+  }
+
+  calculateP95Latency() {
+    if (this.latencies.length === 0) return 0;
+    const sorted = [...this.latencies].sort((a, b) => a - b);
+    const index = Math.ceil(sorted.length * 0.95) - 1;
+    return sorted[Math.max(0, index)];
+  }
+
+  getMetrics() {
+    const total = this.totalSearches || 1;
+    const fallbackRate = (this.fallbackTriggers / total);
+    const zeroRate = (this.zeroResults / total);
+    const p95 = this.calculateP95Latency();
+
+    return {
+      totalSearches: this.totalSearches,
+      fallbackTriggerRate: Number(fallbackRate.toFixed(4)),
+      zeroResultRate: Number(zeroRate.toFixed(4)),
+      searchLatencyP95Ms: p95,
+      circuitBreakerTrips: { ...this.circuitBreakerTrips },
+      searchesByEngine: { ...this.searchesByEngine }
+    };
+  }
+}
+
+export const defaultTelemetry = new SearchTelemetry();

package/server/apiRouter.js

@@ -13,6 +13,8 @@ import { timelineData } from '../src/data/timelineData.js';
 import { PACKAGE_VERSION } from './agent/version.js';
 import { QUIZ_CORRECT_ANSWERS } from './agent/quizData.js';
 import { parseEstimateRequest } from './agent/vramService.js';
+import { toolsSchema } from './agent/tools.js';
+import { toolDefinitions as mcpToolDefinitions } from './mcp/tools.js';
 
 function loadEnv() {
   try {
@@ -2081,7 +2083,7 @@ function renderApiDocsHtml() {
               Kiku AI Agent CLI & MCP Server
             </h2>
             <p class="text-xs sm:text-sm text-stone-600 dark:text-stone-300 mt-1 max-w-3xl">
-              Need an autonomous AI assistant or want to connect Ju Jingyi's knowledge base to Cursor, Claude Desktop, or VS Code? Use the official <strong>kiku-agent</strong> CLI & <strong>kiku-mcp</strong> server with 45 validated tools, local LM Studio (<code class="font-mono text-xs">google/gemma-4-e4b</code>) or cloud LLMs, and multi-agent debate.
+              Need an autonomous AI assistant or want to connect Ju Jingyi's knowledge base to Cursor, Claude Desktop, or VS Code? Use the official <strong>kiku-agent</strong> CLI & <strong>kiku-mcp</strong> server with ${toolsSchema.length} validated tools, local LM Studio (<code class="font-mono text-xs">google/gemma-4-e4b</code>) or cloud LLMs, and multi-agent debate.
             </p>
           </div>
         </div>
@@ -2091,12 +2093,6 @@ function renderApiDocsHtml() {
             <svg class="w-4 h-4" viewBox="0 0 24 24" fill="currentColor"><path d="M1.763 0C.786 0 0 .786 0 1.763v20.474C0 23.214.786 24 1.763 24h20.474c.981 0 1.763-.786 1.763-1.763V1.763C24 .786 23.214 0 22.237 0zM5.13 5.323l13.837.019-.009 13.836h-3.464l.01-10.382h-3.456L12.04 19.17H5.113z"/></svg>
             <span>View on npm</span>
           </a>
-          <a href="/chat" class="px-4 py-2 rounded-xl bg-stone-100 hover:bg-stone-200 dark:bg-stone-800 dark:hover:bg-stone-700 text-stone-800 dark:text-stone-100 font-bold text-xs border border-stone-300 dark:border-stone-700 flex items-center gap-1.5 transition-all active:scale-95">
-            <span>💬 Web Chat</span>
-          </a>
-          <a href="https://github.com/ThemeHackers/jujingyi_kikuuu" target="_blank" rel="noopener noreferrer" class="px-4 py-2 rounded-xl bg-stone-100 hover:bg-stone-200 dark:bg-stone-800 dark:hover:bg-stone-700 text-stone-800 dark:text-stone-100 font-bold text-xs border border-stone-300 dark:border-stone-700 flex items-center gap-1.5 transition-all active:scale-95">
-            <span>GitHub</span>
-          </a>
         </div>
       </div>
 
@@ -2109,7 +2105,7 @@ function renderApiDocsHtml() {
                 <span class="w-2.5 h-2.5 rounded-full bg-rose-500 animate-pulse"></span>
                 <h3 class="font-bold text-stone-900 dark:text-white text-base">Terminal AI Agent (CLI)</h3>
               </div>
-              <span class="font-mono text-xs px-2 py-0.5 rounded bg-rose-50 dark:bg-rose-950 text-rose-700 dark:text-rose-300 border border-rose-200 dark:border-rose-800/60 font-semibold">45 Tools</span>
+              <span class="font-mono text-xs px-2 py-0.5 rounded bg-rose-50 dark:bg-rose-950 text-rose-700 dark:text-rose-300 border border-rose-200 dark:border-rose-800/60 font-semibold">${toolsSchema.length} Tools</span>
             </div>
             <p class="text-xs text-stone-600 dark:text-stone-300 leading-relaxed">
               Autonomous ReAct agent with dynamic multiline input, live thinking reasoning streams, local/cloud LLM switching, background research jobs, YouTube music streaming, and multi-agent debate.
@@ -2151,7 +2147,7 @@ function renderApiDocsHtml() {
                 <span class="w-2.5 h-2.5 rounded-full bg-purple-500 animate-pulse"></span>
                 <h3 class="font-bold text-stone-900 dark:text-white text-base">Model Context Protocol (MCP)</h3>
               </div>
-              <span class="font-mono text-xs px-2 py-0.5 rounded bg-purple-50 dark:bg-purple-950 text-purple-700 dark:text-purple-300 border border-purple-200 dark:border-purple-800/60 font-semibold">43 MCP Tools</span>
+              <span class="font-mono text-xs px-2 py-0.5 rounded bg-purple-50 dark:bg-purple-950 text-purple-700 dark:text-purple-300 border border-purple-200 dark:border-purple-800/60 font-semibold">${mcpToolDefinitions.length} MCP Tools</span>
             </div>
             <p class="text-xs text-stone-600 dark:text-stone-300 leading-relaxed">
               Connect Cursor, Claude Desktop, VS Code, or Antigravity directly to Ju Jingyi's full knowledge base using stdio or Streamable HTTP.
@@ -2181,11 +2177,11 @@ function renderApiDocsHtml() {
   "mcpServers": {
     "kiku": {
       "command": "npx",
-      "args": ["-y", "kiku-agent", "kiku-mcp"]
+      "args": ["-y", "-p", "kiku-agent", "kiku-mcp"]
     }
   }
 }</code></pre>
-                  <button type="button" onclick="copySnippet('{\\n  \\\"mcpServers\\\": {\\n    \\\"kiku\\\": {\\n      \\\"command\\\": \\\"npx\\\",\\n      \\\"args\\\": [\\\"-y\\\", \\\"kiku-agent\\\", \\\"kiku-mcp\\\"]\\n    }\\n  }\\n}', this)" class="absolute top-2 right-2 text-[10px] px-2 py-0.5 rounded bg-purple-800/80 hover:bg-purple-700 text-white cursor-pointer">Copy</button>
+                  <button type="button" onclick="copySnippet('{\\n  \\\"mcpServers\\\": {\\n    \\\"kiku\\\": {\\n      \\\"command\\\": \\\"npx\\\",\\n      \\\"args\\\": [\\\"-y\\\", \\\"-p\\\", \\\"kiku-agent\\\", \\\"kiku-mcp\\\"]\\n    }\\n  }\\n}', this)" class="absolute top-2 right-2 text-[10px] px-2 py-0.5 rounded bg-purple-800/80 hover:bg-purple-700 text-white cursor-pointer">Copy</button>
                 </div>
               </div>
             </div>

package/server/routes/agent.js

@@ -0,0 +1,55 @@
+import { KikuAgent } from '../agent/agentCore.js';
+import { AgentMemory } from '../agent/memory.js';
+import { PUBLIC_REMOTE_TOOL_NAMES } from '../agent/publicTools.js';
+
+export function getSharedAgent(options = {}) {
+  return new KikuAgent({
+    provider: 'lmstudio',
+    apiKey: '',
+    ...options,
+    memory: new AgentMemory({ persistence: false }),
+    sessionPersistence: false,
+    allowedToolNames: PUBLIC_REMOTE_TOOL_NAMES,
+  });
+}
+
+export async function handleAgentChatStream(req, res, queryPrompt, agentOptions = {}) {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-cache, no-transform');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('X-Accel-Buffering', 'no');
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.setHeader('X-Frame-Options', 'DENY');
+  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+
+  const sendEvent = (event, data) => {
+    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  };
+
+  const agent = getSharedAgent(agentOptions);
+  await agent.ready();
+
+  try {
+    sendEvent('start', { prompt: queryPrompt, timestamp: Date.now() });
+
+    await agent.ask(queryPrompt, {
+      onReasoningStart: () => sendEvent('thought_start', {}),
+      onReasoningDelta: (chunk) => sendEvent('thought_delta', { chunk }),
+      onReasoningEnd: () => sendEvent('thought_end', {}),
+      onToolStart: (name, args) => sendEvent('tool_start', { name, args }),
+      onToolResult: (name, result, durationMs) => sendEvent('tool_result', { name, result, durationMs }),
+      onTokenDelta: (chunk) => sendEvent('token', { chunk }),
+      onFinalAnswer: (answer, meta) => sendEvent('done', { answer, meta }),
+      onError: (err) => {
+        console.error('Agent stream error:', err);
+        sendEvent('error', { error: process.env.NODE_ENV === 'development' ? err.message : 'Agent stream execution encountered an issue.' });
+      }
+    });
+  } catch (error) {
+    console.error('Agent chat stream error:', error);
+    sendEvent('error', { error: process.env.NODE_ENV === 'development' ? error.message : 'Agent stream execution failed.' });
+  } finally {
+    res.end();
+  }
+}