ape-claw 0.1.3 → 0.1.5

package/src/server/routes/forge-agent.mjs

@@ -0,0 +1,820 @@
+/**
+ * Routes: POST /api/forge/chat, GET /api/forge/status
+ *
+ * Real OpenClaw agent wrapper for the Forge page.
+ * - Auto-detects LLM provider from environment (Perplexity, OpenAI, Anthropic, Ollama, Groq, or any OpenAI-compatible endpoint)
+ * - Loads skills from ~/.openclaw/skills/ at startup
+ * - Registered ClawBot identity (FORGE_AGENT_ID / FORGE_AGENT_TOKEN)
+ * - Fetches live telemetry snapshot on each request
+ * - Streams responses back to the browser via SSE
+ * - Posts conversations to chat log + emits telemetry events
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { getStorage } from "../storage/index.mjs";
+import { collectBody } from "../middleware/body-limit.mjs";
+import { CLAWBOTS_PATH } from "../../lib/paths.mjs";
+import { registerClawbot, verifyClawbot } from "../../lib/clawbots.mjs";
+import logger from "../logger.mjs";
+
+const SKILL_RESCAN_INTERVAL_MS = 5 * 60 * 1000;
+const MAX_HISTORY_TURNS = 10;
+const MAX_MESSAGE_LENGTH = 500;
+
+const FORGE_AGENT_ID = String(process.env.FORGE_AGENT_ID || "the-clawllector").trim();
+const FORGE_AGENT_TOKEN = String(process.env.FORGE_AGENT_TOKEN || "").trim();
+const FORGE_AGENT_DISPLAY_NAME = String(process.env.FORGE_AGENT_NAME || "The Clawllector").trim();
+
+const RATE_LIMIT_WINDOW_MS = 60_000;
+const RATE_LIMIT_MAX = 10;
+const rateBuckets = new Map();
+
+let cachedSkills = { apeClawFull: "", summaries: [], loadedAt: 0 };
+let runtimeAgentToken = FORGE_AGENT_TOKEN;
+let runtimeAgentVerified = false;
+
+/* ══════════════════════════════════════════════════════════
+   LLM Provider Detection
+   Auto-detects from env vars. Priority:
+   1. Explicit FORGE_LLM_* overrides (any OpenAI-compatible endpoint)
+   2. PERPLEXITY_API_KEY
+   3. OPENAI_API_KEY
+   4. ANTHROPIC_API_KEY
+   5. GROQ_API_KEY
+   6. TOGETHER_API_KEY
+   7. OLLAMA_HOST / OLLAMA_BASE_URL (no key needed)
+   ══════════════════════════════════════════════════════════ */
+
+const PROVIDER_DEFAULTS = {
+  custom:     { url: null,                                           model: "gpt-4o" },
+  perplexity: { url: "https://api.perplexity.ai/chat/completions",   model: "sonar-pro" },
+  openai:     { url: "https://api.openai.com/v1/chat/completions",   model: "gpt-4o" },
+  anthropic:  { url: "https://api.anthropic.com/v1/messages",        model: "claude-sonnet-4-20250514" },
+  groq:       { url: "https://api.groq.com/openai/v1/chat/completions", model: "llama-3.3-70b-versatile" },
+  together:   { url: "https://api.together.xyz/v1/chat/completions", model: "meta-llama/Llama-3.3-70B-Instruct-Turbo" },
+  ollama:     { url: "http://localhost:11434/v1/chat/completions",   model: "llama3.2" },
+};
+
+function detectLlmProvider() {
+  const explicit = (process.env.FORGE_LLM_API_URL || "").trim();
+  const explicitKey = (process.env.FORGE_LLM_API_KEY || "").trim();
+  const explicitModel = (process.env.FORGE_LLM_MODEL || process.env.FORGE_AGENT_MODEL || "").trim();
+
+  if (explicit) {
+    return {
+      provider: "custom",
+      apiUrl: explicit,
+      apiKey: explicitKey,
+      model: explicitModel || PROVIDER_DEFAULTS.custom.model,
+      isAnthropic: explicit.includes("anthropic.com"),
+    };
+  }
+
+  const perplexity = (process.env.PERPLEXITY_API_KEY || "").trim();
+  if (perplexity) {
+    return {
+      provider: "perplexity",
+      apiUrl: PROVIDER_DEFAULTS.perplexity.url,
+      apiKey: perplexity,
+      model: explicitModel || PROVIDER_DEFAULTS.perplexity.model,
+      isAnthropic: false,
+    };
+  }
+
+  const openai = (process.env.OPENAI_API_KEY || "").trim();
+  if (openai) {
+    return {
+      provider: "openai",
+      apiUrl: PROVIDER_DEFAULTS.openai.url,
+      apiKey: openai,
+      model: explicitModel || PROVIDER_DEFAULTS.openai.model,
+      isAnthropic: false,
+    };
+  }
+
+  const anthropic = (process.env.ANTHROPIC_API_KEY || "").trim();
+  if (anthropic) {
+    return {
+      provider: "anthropic",
+      apiUrl: PROVIDER_DEFAULTS.anthropic.url,
+      apiKey: anthropic,
+      model: explicitModel || PROVIDER_DEFAULTS.anthropic.model,
+      isAnthropic: true,
+    };
+  }
+
+  const groq = (process.env.GROQ_API_KEY || "").trim();
+  if (groq) {
+    return {
+      provider: "groq",
+      apiUrl: PROVIDER_DEFAULTS.groq.url,
+      apiKey: groq,
+      model: explicitModel || PROVIDER_DEFAULTS.groq.model,
+      isAnthropic: false,
+    };
+  }
+
+  const together = (process.env.TOGETHER_API_KEY || "").trim();
+  if (together) {
+    return {
+      provider: "together",
+      apiUrl: PROVIDER_DEFAULTS.together.url,
+      apiKey: together,
+      model: explicitModel || PROVIDER_DEFAULTS.together.model,
+      isAnthropic: false,
+    };
+  }
+
+  const ollamaHost = (process.env.OLLAMA_HOST || process.env.OLLAMA_BASE_URL || "").trim();
+  if (ollamaHost) {
+    const base = ollamaHost.replace(/\/+$/, "");
+    return {
+      provider: "ollama",
+      apiUrl: `${base}/v1/chat/completions`,
+      apiKey: "",
+      model: explicitModel || PROVIDER_DEFAULTS.ollama.model,
+      isAnthropic: false,
+    };
+  }
+
+  return null;
+}
+
+const llmConfig = detectLlmProvider();
+
+/* ══════════════════════════════════════════════════════════
+   Skill Loader — reads from ~/.openclaw/skills/ and fallback
+   ══════════════════════════════════════════════════════════ */
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\s*/);
+  if (!match) return { meta: {}, body: content };
+  const meta = {};
+  for (const line of match[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      const key = line.slice(0, idx).trim();
+      let val = line.slice(idx + 1).trim();
+      if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+      meta[key] = val;
+    }
+  }
+  return { meta, body: content.slice(match[0].length) };
+}
+
+function loadSkillsFromDir(dir) {
+  const skills = [];
+  if (!fs.existsSync(dir)) return skills;
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return skills; }
+  for (const name of entries) {
+    const skillMd = path.join(dir, name, "SKILL.md");
+    if (!fs.existsSync(skillMd)) continue;
+    try {
+      const raw = fs.readFileSync(skillMd, "utf8");
+      const { meta, body } = parseFrontmatter(raw);
+      skills.push({
+        slug: name,
+        name: meta.name || name,
+        description: meta.description || "",
+        version: meta.version || "",
+        fullContent: raw,
+        body,
+      });
+    } catch {}
+  }
+  return skills;
+}
+
+function findOpenClawBundledSkillsDir() {
+  try {
+    const bin = execSync("which openclaw", { encoding: "utf8" }).trim();
+    if (bin) {
+      const resolved = fs.realpathSync(bin);
+      const pkgDir = path.resolve(path.dirname(resolved), "..", "lib", "node_modules", "openclaw", "skills");
+      if (fs.existsSync(pkgDir)) return pkgDir;
+      const altDir = path.resolve(path.dirname(resolved), "..", "node_modules", "openclaw", "skills");
+      if (fs.existsSync(altDir)) return altDir;
+    }
+  } catch {}
+  const globalPaths = [
+    "/usr/local/lib/node_modules/openclaw/skills",
+    "/usr/lib/node_modules/openclaw/skills",
+    path.join(os.homedir(), ".npm-global", "lib", "node_modules", "openclaw", "skills"),
+  ];
+  for (const p of globalPaths) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+let _openclawBundledDir = undefined;
+
+function refreshSkillCache() {
+  const now = Date.now();
+  if (now - cachedSkills.loadedAt < SKILL_RESCAN_INTERVAL_MS) return;
+
+  const seen = new Set();
+  const allSkills = [];
+
+  function addSkillsFrom(dir) {
+    for (const s of loadSkillsFromDir(dir)) {
+      if (!seen.has(s.slug)) {
+        seen.add(s.slug);
+        allSkills.push(s);
+      }
+    }
+  }
+
+  addSkillsFrom(path.join(os.homedir(), ".openclaw", "skills"));
+
+  if (_openclawBundledDir === undefined) {
+    _openclawBundledDir = findOpenClawBundledSkillsDir();
+    if (_openclawBundledDir) logger.info({ dir: _openclawBundledDir }, "Found OpenClaw bundled skills");
+  }
+  if (_openclawBundledDir) addSkillsFrom(_openclawBundledDir);
+
+  addSkillsFrom(path.join(process.cwd(), "data", "forge-skills"));
+
+  addSkillsFrom(path.join(process.cwd(), ".cursor", "skills"));
+
+  const skills = allSkills;
+
+  const apeClaw = skills.find((s) => s.slug === "ape-claw");
+  const summaries = skills
+    .filter((s) => s.slug !== "ape-claw")
+    .map((s) => `- **${s.name}**: ${s.description || "(no description)"}`)
+    .slice(0, 80);
+
+  cachedSkills = {
+    apeClawFull: apeClaw?.fullContent || "",
+    summaries,
+    loadedAt: now,
+  };
+
+  logger.info({ skillCount: skills.length, source: skills.length > 0 ? "openclaw" : "fallback" }, "Forge agent skills loaded");
+}
+
+function ensureForgeAgentIdentity() {
+  if (runtimeAgentToken) {
+    const check = verifyClawbot({ agentId: FORGE_AGENT_ID, agentToken: runtimeAgentToken });
+    if (check.verified) {
+      runtimeAgentVerified = true;
+      return;
+    }
+    logger.warn({ reason: check.reason }, "FORGE_AGENT_TOKEN provided but verification failed");
+  }
+
+  try {
+    const reg = registerClawbot({ agentId: FORGE_AGENT_ID, displayName: FORGE_AGENT_DISPLAY_NAME });
+    runtimeAgentToken = reg.token;
+    runtimeAgentVerified = true;
+    logger.info({ agentId: reg.agentId }, "Forge agent auto-registered as clawbot");
+  } catch (err) {
+    runtimeAgentVerified = false;
+    logger.warn(
+      { err: err?.message || String(err) },
+      "Forge agent auto-registration unavailable; set FORGE_AGENT_TOKEN for verified identity",
+    );
+  }
+}
+
+/* ══════════════════════════════════════════════════════════
+   Telemetry Snapshot — direct storage access
+   ══════════════════════════════════════════════════════════ */
+
+function getTelemetrySnapshot() {
+  const store = getStorage();
+  const snapshot = {};
+
+  try {
+    const events = store.getEventBacklog(15);
+    snapshot.recentEvents = events.slice(-15).map((e) => {
+      const ts = e.ts ? new Date(e.ts).toLocaleString() : "?";
+      return `[${ts}] ${e.eventType} by ${e.agentId || "unknown"}${e.command ? ` (${e.command})` : ""}${e.ok === false ? " FAILED" : ""}`;
+    });
+  } catch { snapshot.recentEvents = []; }
+
+  try {
+    const chatEntries = store.readChatEntries();
+    const messages = chatEntries
+      .filter((e) => e.type === "message")
+      .slice(-10);
+    snapshot.recentChat = messages.map((m) => `[${m.agentName || m.agentId || "?"}] ${(m.text || "").slice(0, 120)}`);
+  } catch { snapshot.recentChat = []; }
+
+  try {
+    if (fs.existsSync(CLAWBOTS_PATH)) {
+      const raw = JSON.parse(fs.readFileSync(CLAWBOTS_PATH, "utf8"));
+      const agents = raw.agents || {};
+      const bots = Object.entries(agents).map(([id, a]) => ({
+        id, name: a.name || id, enabled: a.enabled !== false,
+      }));
+      snapshot.clawbots = bots;
+    } else {
+      snapshot.clawbots = [];
+    }
+  } catch { snapshot.clawbots = []; }
+
+  try {
+    const all = store.getMergedSkillIndex();
+    const onchain = all.filter((s) => s.onchainTokenId != null).length;
+    const seed = all.filter((s) => s.source === "seed").length;
+    const imported = all.filter((s) => s.source === "imported").length;
+    const user = all.filter((s) => s.source === "user").length;
+    snapshot.skillStats = { total: all.length, seed, imported, user, onchain };
+  } catch { snapshot.skillStats = { total: 0 }; }
+
+  try {
+    const userIdx = store.getUserSkillsIndex();
+    const userSkills = Array.isArray(userIdx?.skills) ? userIdx.skills : [];
+    snapshot.userInstalledSkills = userSkills.length;
+  } catch { snapshot.userInstalledSkills = 0; }
+
+  try { snapshot.quoteSpend = store.getQuotesSpendToday(); } catch { snapshot.quoteSpend = 0; }
+  try { snapshot.bridgeSpend = store.getBridgeSpendToday(); } catch { snapshot.bridgeSpend = 0; }
+
+  try {
+    const podWs = store.findPodWorkspaceDir();
+    if (podWs) {
+      const stopped = fs.existsSync(path.join(podWs, "stop.flag"));
+      const hasAgents = fs.existsSync(path.join(podWs, "AGENTS.md"));
+      let lastHeartbeat = null;
+      const hbPath = path.join(podWs, "state", "last-heartbeat.json");
+      if (fs.existsSync(hbPath)) {
+        try { lastHeartbeat = JSON.parse(fs.readFileSync(hbPath, "utf8"))?.timestamp || null; } catch {}
+      }
+      snapshot.pod = { status: hasAgents ? (stopped ? "stopped" : "running") : "not-initialized", lastHeartbeat };
+    } else {
+      snapshot.pod = { status: "not-initialized" };
+    }
+  } catch { snapshot.pod = { status: "unknown" }; }
+
+  return snapshot;
+}
+
+function formatTelemetryContext(snapshot) {
+  const lines = ["## Live Telemetry (real-time data from the backend)"];
+
+  const bots = snapshot.clawbots || [];
+  const activeNames = bots.filter((b) => b.enabled).map((b) => b.name).slice(0, 20);
+  lines.push(`- Registered clawbots: ${bots.length} total${activeNames.length ? ` (${activeNames.join(", ")})` : ""}`);
+
+  const ss = snapshot.skillStats || {};
+  lines.push(`- Skills library: ${ss.total || 0} total (${ss.seed || 0} seed, ${ss.imported || 0} imported, ${ss.user || 0} user), ${ss.onchain || 0} onchain`);
+  lines.push(`- User-installed skill records: ${snapshot.userInstalledSkills || 0}`);
+
+  lines.push(`- Daily spend: NFT quotes ${snapshot.quoteSpend || 0} APE / Bridge ${snapshot.bridgeSpend || 0} APE`);
+  lines.push(`- Pod status: ${snapshot.pod?.status || "unknown"}${snapshot.pod?.lastHeartbeat ? `, last heartbeat ${snapshot.pod.lastHeartbeat}` : ""}`);
+
+  if (snapshot.recentEvents?.length) {
+    lines.push("", "### Recent telemetry events");
+    for (const e of snapshot.recentEvents.slice(-10)) lines.push(`  ${e}`);
+  }
+
+  if (snapshot.recentChat?.length) {
+    lines.push("", "### Recent forge chat");
+    for (const m of snapshot.recentChat.slice(-5)) lines.push(`  ${m}`);
+  }
+
+  return lines.join("\n");
+}
+
+/* ══════════════════════════════════════════════════════════
+   System Prompt Builder
+   ══════════════════════════════════════════════════════════ */
+
+function buildSystemPrompt(snapshot) {
+  refreshSkillCache();
+
+  const providerLabel = llmConfig ? `${llmConfig.provider} (${llmConfig.model})` : "unknown";
+
+  const parts = [
+    `You are ${FORGE_AGENT_DISPLAY_NAME}, a real OpenClaw agent with the ape-claw skill set installed. You are a registered ClawBot (agentId: ${FORGE_AGENT_ID}).`,
+    "",
+    "## Identity",
+    `- Registered ClawBot: ${FORGE_AGENT_ID}`,
+    "- Framework: OpenClaw (openclaw.ai) — a personal AI assistant framework that runs on your machine",
+    `- LLM provider: ${providerLabel}`,
+    `- Skills installed: ${cachedSkills.summaries.length + (cachedSkills.apeClawFull ? 1 : 0)}`,
+    "",
+  ];
+
+  if (cachedSkills.apeClawFull) {
+    parts.push("## Ape-Claw Skill Knowledge (your primary skill)");
+    parts.push(cachedSkills.apeClawFull);
+    parts.push("");
+  }
+
+  parts.push(formatTelemetryContext(snapshot));
+
+  if (cachedSkills.summaries.length) {
+    parts.push("", "## Other Installed Skills");
+    parts.push(...cachedSkills.summaries);
+  }
+
+  parts.push("", "## Behavior");
+  parts.push("- You have REAL access to live backend data — cite it when users ask about activity, bots, skills, or spend.");
+  parts.push("- Guide users through getting started with ApeClaw and OpenClaw.");
+  parts.push("- Reference specific CLI commands from the ape-claw skill (e.g. `npx ape-claw skill install`, `npx ape-claw doctor --json`).");
+  parts.push("- Be direct, concise, and knowledgeable about ApeChain, NFTs, and Web3.");
+  parts.push("- When asked about skills, reference the real library stats and help users find what they need.");
+  parts.push("- Do NOT hallucinate capabilities — stick to what ApeClaw actually ships.");
+  parts.push("- Keep responses focused and practical. Use short paragraphs.");
+  parts.push("- Prefer plain conversational output with light formatting only (bold, short bullets).");
+  parts.push("- Do NOT include citation markers like [1], [2], or footnote-style references unless the user explicitly asks for sources.");
+
+  return parts.join("\n");
+}
+
+function normalizeConversationHistory(history) {
+  const cleaned = [];
+  for (const turn of history) {
+    const role = turn?.role === "assistant" ? "assistant" : "user";
+    const content = String(turn?.content || "").trim();
+    if (!content) continue;
+    cleaned.push({ role, content: content.slice(0, 2000) });
+  }
+
+  // Perplexity/OpenAI-compatible endpoints expect strict user/assistant alternation.
+  // Start from user, skip invalid out-of-order turns.
+  const alternating = [];
+  let expectedRole = "user";
+  for (const turn of cleaned) {
+    if (turn.role !== expectedRole) continue;
+    alternating.push(turn);
+    expectedRole = expectedRole === "user" ? "assistant" : "user";
+  }
+
+  // If history ends with a user turn, drop it because we'll append a fresh user message.
+  if (alternating.length && alternating[alternating.length - 1].role === "user") {
+    alternating.pop();
+  }
+
+  return alternating;
+}
+
+/* ══════════════════════════════════════════════════════════
+   Actions — post to chat log + emit telemetry
+   ══════════════════════════════════════════════════════════ */
+
+function postToChat(room, text, role) {
+  try {
+    const store = getStorage();
+    const msg = {
+      id: `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      type: "message",
+      agentId: role === "user" ? "forge-visitor" : FORGE_AGENT_ID,
+      agentName: role === "user" ? "Forge Visitor" : FORGE_AGENT_DISPLAY_NAME,
+      identityProvider: role === "user" ? "anonymous" : (runtimeAgentVerified ? "clawbot" : "clawbot-unverified"),
+      identityMeta: role === "user" ? {} : { verified: runtimeAgentVerified, source: "forge-agent" },
+      room,
+      text: text.slice(0, 500),
+      replyTo: null,
+      reactions: {},
+      reactionUsers: {},
+      ts: new Date().toISOString(),
+    };
+    store.appendChat(msg);
+  } catch (err) {
+    logger.warn({ err }, "Failed to post forge agent chat");
+  }
+}
+
+function emitTelemetryEvent(userMessage, responseLength) {
+  try {
+    const store = getStorage();
+    store.appendEvent({
+      v: 1,
+      ts: new Date().toISOString(),
+      eventType: "forge-agent-response",
+      agentId: FORGE_AGENT_ID,
+      sessionId: "forge-web",
+      traceId: `forge_${Date.now()}`,
+      command: "forge-chat",
+      dryRun: false,
+      chainId: 33139,
+      payload: { messageLength: userMessage.length, responseLength, provider: llmConfig?.provider },
+      result: { ok: true },
+      ok: true,
+      error: null,
+      source: "forge-agent",
+    });
+  } catch (err) {
+    logger.warn({ err }, "Failed to emit forge agent telemetry");
+  }
+}
+
+/* ══════════════════════════════════════════════════════════
+   Rate Limiting (IP-based, for unauthenticated visitors)
+   ══════════════════════════════════════════════════════════ */
+
+function checkForgeRateLimit(req) {
+  const xff = String(req.headers["x-forwarded-for"] || "").trim();
+  const ip = xff ? xff.split(",")[0].trim() : String(req.socket?.remoteAddress || "unknown");
+  const now = Date.now();
+  const bucket = rateBuckets.get(ip);
+  if (!bucket || now - bucket.windowStart > RATE_LIMIT_WINDOW_MS) {
+    rateBuckets.set(ip, { windowStart: now, count: 1 });
+    return null;
+  }
+  bucket.count++;
+  if (bucket.count > RATE_LIMIT_MAX) {
+    return { retryAfterMs: RATE_LIMIT_WINDOW_MS - (now - bucket.windowStart) };
+  }
+  return null;
+}
+
+setInterval(() => {
+  const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS * 2;
+  for (const [ip, bucket] of rateBuckets) {
+    if (bucket.windowStart < cutoff) rateBuckets.delete(ip);
+  }
+}, 120_000).unref();
+
+/* ══════════════════════════════════════════════════════════
+   LLM Streaming — OpenAI-compatible (covers most providers)
+   ══════════════════════════════════════════════════════════ */
+
+async function streamOpenAICompatible(messages, res) {
+  const headers = { "content-type": "application/json" };
+  if (llmConfig.apiKey) headers["authorization"] = `Bearer ${llmConfig.apiKey}`;
+
+  async function requestOnce() {
+    return fetch(llmConfig.apiUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ model: llmConfig.model, messages, stream: true }),
+    });
+  }
+  let upstream = await requestOnce();
+  if (!upstream.ok && (upstream.status === 429 || upstream.status >= 500)) {
+    const retryAfter = Number(upstream.headers.get("retry-after") || 0);
+    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1000, 4000) : 500;
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+    upstream = await requestOnce();
+  }
+
+  if (!upstream.ok) {
+    const errText = await upstream.text().catch(() => "");
+    logger.error({ status: upstream.status, body: errText.slice(0, 500), provider: llmConfig.provider }, "LLM API error");
+    res.writeHead(502, { "content-type": "application/json" });
+    const retryAfter = Number(upstream.headers.get("retry-after") || 0) || undefined;
+    return res.end(JSON.stringify({
+      error: `upstream API error (${llmConfig.provider} ${upstream.status})`,
+      status: upstream.status,
+      provider: llmConfig.provider,
+      retryAfter,
+    }));
+  }
+
+  res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "connection": "keep-alive" });
+
+  let fullResponse = "";
+  const reader = upstream.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      if (!line.startsWith("data: ")) continue;
+      const data = line.slice(6).trim();
+      if (data === "[DONE]") { res.write("data: [DONE]\n\n"); continue; }
+      try {
+        const chunk = JSON.parse(data);
+        const text = chunk.choices?.[0]?.delta?.content || "";
+        if (text) {
+          fullResponse += text;
+          res.write(`data: ${JSON.stringify({ text })}\n\n`);
+        }
+      } catch {}
+    }
+  }
+
+  if (buffer.trim()) {
+    const remaining = buffer.trim();
+    if (remaining.startsWith("data: ") && remaining.slice(6).trim() !== "[DONE]") {
+      try {
+        const chunk = JSON.parse(remaining.slice(6).trim());
+        const text = chunk.choices?.[0]?.delta?.content || "";
+        if (text) { fullResponse += text; res.write(`data: ${JSON.stringify({ text })}\n\n`); }
+      } catch {}
+    }
+  }
+
+  if (!res.writableEnded) { res.write("data: [DONE]\n\n"); res.end(); }
+  return fullResponse;
+}
+
+/* ══════════════════════════════════════════════════════════
+   LLM Streaming — Anthropic Messages API
+   ══════════════════════════════════════════════════════════ */
+
+async function streamAnthropic(systemPrompt, messages, res) {
+  const anthropicMessages = messages
+    .filter((m) => m.role !== "system")
+    .map((m) => ({ role: m.role, content: m.content }));
+
+  async function requestOnce() {
+    return fetch(llmConfig.apiUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": llmConfig.apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: llmConfig.model,
+        max_tokens: 2048,
+        system: systemPrompt,
+        messages: anthropicMessages,
+        stream: true,
+      }),
+    });
+  }
+  let upstream = await requestOnce();
+  if (!upstream.ok && (upstream.status === 429 || upstream.status >= 500)) {
+    const retryAfter = Number(upstream.headers.get("retry-after") || 0);
+    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1000, 4000) : 500;
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+    upstream = await requestOnce();
+  }
+
+  if (!upstream.ok) {
+    const errText = await upstream.text().catch(() => "");
+    logger.error({ status: upstream.status, body: errText.slice(0, 500), provider: "anthropic" }, "Anthropic API error");
+    res.writeHead(502, { "content-type": "application/json" });
+    const retryAfter = Number(upstream.headers.get("retry-after") || 0) || undefined;
+    return res.end(JSON.stringify({
+      error: `upstream API error (anthropic ${upstream.status})`,
+      status: upstream.status,
+      provider: "anthropic",
+      retryAfter,
+    }));
+  }
+
+  res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "connection": "keep-alive" });
+
+  let fullResponse = "";
+  const reader = upstream.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      if (line.startsWith("event: ")) continue;
+      if (!line.startsWith("data: ")) continue;
+      const data = line.slice(6).trim();
+      if (!data) continue;
+      try {
+        const evt = JSON.parse(data);
+        if (evt.type === "content_block_delta" && evt.delta?.text) {
+          fullResponse += evt.delta.text;
+          res.write(`data: ${JSON.stringify({ text: evt.delta.text })}\n\n`);
+        }
+        if (evt.type === "message_stop") {
+          res.write("data: [DONE]\n\n");
+        }
+      } catch {}
+    }
+  }
+
+  if (!res.writableEnded) { res.write("data: [DONE]\n\n"); res.end(); }
+  return fullResponse;
+}
+
+/* ══════════════════════════════════════════════════════════
+   Init — called at server startup
+   ══════════════════════════════════════════════════════════ */
+
+export function initForgeAgent() {
+  if (!llmConfig) {
+    logger.warn(
+      "No LLM provider detected — forge agent will return 503. " +
+      "Set one of: PERPLEXITY_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, " +
+      "TOGETHER_API_KEY, OLLAMA_HOST, or FORGE_LLM_API_URL",
+    );
+  } else {
+    logger.info({ provider: llmConfig.provider, model: llmConfig.model, hasKey: Boolean(llmConfig.apiKey) }, "LLM provider detected");
+  }
+  ensureForgeAgentIdentity();
+  refreshSkillCache();
+  logger.info(
+    {
+      agentId: FORGE_AGENT_ID,
+      verified: runtimeAgentVerified,
+      provider: llmConfig?.provider || "none",
+      model: llmConfig?.model,
+      skills: cachedSkills.summaries.length + (cachedSkills.apeClawFull ? 1 : 0),
+    },
+    "Forge agent initialized",
+  );
+}
+
+/* ══════════════════════════════════════════════════════════
+   Status — GET /api/forge/status
+   ══════════════════════════════════════════════════════════ */
+
+export function handleForgeStatus(req, res) {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify({
+    configured: Boolean(llmConfig),
+    provider: llmConfig?.provider || null,
+    agentId: FORGE_AGENT_ID,
+    agentName: FORGE_AGENT_DISPLAY_NAME,
+    verified: runtimeAgentVerified,
+    model: llmConfig?.model || null,
+    skills: cachedSkills.summaries.length + (cachedSkills.apeClawFull ? 1 : 0),
+  }));
+}
+
+/* ══════════════════════════════════════════════════════════
+   Handler — POST /api/forge/chat
+   ══════════════════════════════════════════════════════════ */
+
+export async function handleForgeChat(req, res) {
+  if (!llmConfig) {
+    res.writeHead(503, { "content-type": "application/json" });
+    return res.end(JSON.stringify({
+      error: "Forge agent not configured. Set one of: PERPLEXITY_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY, OLLAMA_HOST, or FORGE_LLM_API_URL",
+    }));
+  }
+
+  const rl = checkForgeRateLimit(req);
+  if (rl) {
+    res.writeHead(429, { "content-type": "application/json" });
+    return res.end(JSON.stringify({ error: "rate limited", retryAfterMs: rl.retryAfterMs }));
+  }
+
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+
+  let body;
+  try { body = JSON.parse(raw); } catch {
+    res.writeHead(400, { "content-type": "application/json" });
+    return res.end(JSON.stringify({ error: "invalid JSON body" }));
+  }
+
+  const userMessage = String(body.message || body.text || "").trim();
+  if (!userMessage || userMessage.length > MAX_MESSAGE_LENGTH) {
+    res.writeHead(400, { "content-type": "application/json" });
+    return res.end(JSON.stringify({ error: `message must be 1-${MAX_MESSAGE_LENGTH} characters` }));
+  }
+
+  const history = Array.isArray(body.history) ? body.history.slice(-MAX_HISTORY_TURNS) : [];
+
+  const snapshot = getTelemetrySnapshot();
+  const systemPrompt = buildSystemPrompt(snapshot);
+
+  const messages = [{ role: "system", content: systemPrompt }];
+  const normalizedHistory = normalizeConversationHistory(history);
+  for (const turn of normalizedHistory) {
+    messages.push(turn);
+  }
+  messages.push({ role: "user", content: userMessage });
+
+  postToChat("forge", userMessage, "user");
+
+  try {
+    let fullResponse;
+
+    if (llmConfig.isAnthropic) {
+      fullResponse = await streamAnthropic(systemPrompt, messages, res);
+    } else {
+      fullResponse = await streamOpenAICompatible(messages, res);
+    }
+
+    if (fullResponse) {
+      postToChat("forge", fullResponse.slice(0, 500), "agent");
+      emitTelemetryEvent(userMessage, fullResponse.length);
+    }
+  } catch (err) {
+    logger.error({ err, provider: llmConfig.provider }, "Forge agent stream error");
+    if (!res.headersSent) {
+      res.writeHead(500, { "content-type": "application/json" });
+      return res.end(JSON.stringify({ error: "internal error" }));
+    }
+    if (!res.writableEnded) {
+      res.write(`data: ${JSON.stringify({ text: "\n\n[Connection interrupted]" })}\n\n`);
+      res.write("data: [DONE]\n\n");
+      res.end();
+    }
+  }
+}