ape-claw 0.1.0

package/src/server/middleware/rate-limit.mjs

@@ -0,0 +1,44 @@
+const buckets = new Map();
+
+function clientKey(req, prefix) {
+  const xff = String(req.headers["x-forwarded-for"] || "").trim();
+  const ip = xff ? xff.split(",")[0].trim() : String(req.socket?.remoteAddress || "unknown");
+  return `${prefix}:${ip}`;
+}
+
+/**
+ * Returns true (and sends 429) if the request exceeds the rate limit.
+ * Returns false if the request is within limits.
+ */
+export function checkRateLimit(req, res, { limit = 60, windowMs = 60_000, keyPrefix = "default" } = {}) {
+  const key = clientKey(req, keyPrefix);
+  const now = Date.now();
+  let bucket = buckets.get(key);
+
+  if (!bucket || now - bucket.windowStart > windowMs) {
+    bucket = { windowStart: now, count: 0 };
+    buckets.set(key, bucket);
+  }
+
+  bucket.count++;
+
+  if (bucket.count > limit) {
+    const retryAfter = Math.ceil((bucket.windowStart + windowMs - now) / 1000);
+    res.writeHead(429, {
+      "content-type": "application/json",
+      "retry-after": String(retryAfter),
+    });
+    res.end(JSON.stringify({ error: "rate limit exceeded", retryAfterSeconds: retryAfter }));
+    return true;
+  }
+
+  return false;
+}
+
+// Purge stale buckets every 5 minutes
+setInterval(() => {
+  const cutoff = Date.now() - 300_000;
+  for (const [key, bucket] of buckets) {
+    if (bucket.windowStart < cutoff) buckets.delete(key);
+  }
+}, 300_000).unref();

package/src/server/routes/chat.mjs

@@ -0,0 +1,178 @@
+/**
+ * Routes: /api/chat/*, /api/chat/stream (SSE)
+ */
+
+import { getStorage } from "../storage/index.mjs";
+import { addChatClient } from "../sse.mjs";
+import { resolveChatAuth } from "../middleware/auth.mjs";
+import { collectBody } from "../middleware/body-limit.mjs";
+
+function normalizeRoomName(input) {
+  const raw = String(input || "general").toLowerCase().trim()
+    .replace(/[^a-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return raw || "general";
+}
+
+function materializeChatMessages(entries, room = "all") {
+  const targetRoom = normalizeRoomName(room);
+  const byId = new Map();
+  const ordered = [];
+
+  for (const e of entries) {
+    if (String(e.type || "message") !== "message") continue;
+    const msg = {
+      id: e.id, type: "message", agentId: e.agentId, agentName: e.agentName,
+      identityProvider: e.identityProvider, identityMeta: e.identityMeta || {},
+      room: normalizeRoomName(e.room || "general"), text: e.text, ts: e.ts,
+      replyTo: e.replyTo || null, reactions: {}, reactionUsers: {},
+    };
+    byId.set(msg.id, msg);
+    ordered.push(msg);
+  }
+
+  for (const e of entries) {
+    if (String(e.type || "") !== "reaction") continue;
+    const msg = byId.get(e.messageId);
+    if (!msg) continue;
+    const emoji = String(e.emoji || "").trim();
+    const agentId = String(e.agentId || "").trim();
+    if (!emoji || !agentId) continue;
+    const current = new Set(msg.reactionUsers[emoji] || []);
+    if (current.has(agentId)) current.delete(agentId);
+    else current.add(agentId);
+    msg.reactionUsers[emoji] = [...current];
+    msg.reactions[emoji] = msg.reactionUsers[emoji].length;
+  }
+
+  return targetRoom === "all" ? ordered : ordered.filter((m) => normalizeRoomName(m.room) === targetRoom);
+}
+
+export function handleChatStream(req, res, reqUrl) {
+  const room = normalizeRoomName(reqUrl.searchParams.get("room") || "all");
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+  });
+  res.write("\n");
+  const remove = addChatClient(res, room);
+  req.on("close", remove);
+}
+
+export function handleChatGet(req, res, reqUrl) {
+  const store = getStorage();
+  const room = normalizeRoomName(reqUrl.searchParams.get("room") || "all");
+  const limit = Math.max(1, Math.min(500, Number(reqUrl.searchParams.get("limit") || 100)));
+  const entries = store.readChatEntries();
+  const messages = materializeChatMessages(entries, room).slice(-limit);
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ room, limit, messages }));
+}
+
+export function handleChatRooms(req, res, reqUrl) {
+  const store = getStorage();
+  const limit = Math.max(1, Math.min(200, Number(reqUrl.searchParams.get("limit") || 50)));
+  const parsed = materializeChatMessages(store.readChatEntries(), "all");
+  const byRoom = new Map();
+  for (const m of parsed) {
+    const room = normalizeRoomName(m.room || "general");
+    const prev = byRoom.get(room) || { room, count: 0, lastTs: null, lastMessage: "", participants: new Set() };
+    prev.count += 1;
+    prev.lastTs = m.ts || prev.lastTs;
+    prev.lastMessage = m.text || prev.lastMessage;
+    if (m.agentId) prev.participants.add(m.agentId);
+    byRoom.set(room, prev);
+  }
+  const rooms = [...byRoom.values()]
+    .map((r) => ({ room: r.room, count: r.count, lastTs: r.lastTs, lastMessage: r.lastMessage, participants: r.participants.size }))
+    .sort((a, b) => String(b.lastTs || "").localeCompare(String(a.lastTs || "")))
+    .slice(0, limit);
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ count: rooms.length, rooms }));
+}
+
+export async function handleChatPost(req, res, reqUrl) {
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const store = getStorage();
+    const room = normalizeRoomName(body.room || reqUrl.searchParams.get("room") || "general");
+    const text = String(body.text || "").trim();
+    const replyTo = String(body.replyTo || "").trim();
+
+    if (!text || text.length > 500) {
+      res.writeHead(400, { "content-type": "application/json" });
+      return res.end(JSON.stringify({ error: "message must be 1-500 characters" }));
+    }
+    const authRes = await resolveChatAuth(req, body);
+    if (!authRes.ok) {
+      res.writeHead(authRes.status || 403, { "content-type": "application/json" });
+      return res.end(JSON.stringify({ error: authRes.error, reason: authRes.reason }));
+    }
+    const auth = authRes.auth;
+
+    if (replyTo) {
+      const existing = materializeChatMessages(store.readChatEntries(), room);
+      const parent = existing.find((m) => m.id === replyTo);
+      if (!parent) {
+        res.writeHead(400, { "content-type": "application/json" });
+        return res.end(JSON.stringify({ error: "reply target not found in this room" }));
+      }
+    }
+
+    const msg = {
+      id: `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      type: "message", agentId: auth.id, agentName: auth.name,
+      identityProvider: auth.provider, identityMeta: auth.meta,
+      room, text, replyTo: replyTo || null, reactions: {}, reactionUsers: {},
+      ts: new Date().toISOString(),
+    };
+    store.appendChat(msg);
+
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, message: msg }));
+  } catch {
+    res.writeHead(400, { "content-type": "application/json" });
+    return res.end(JSON.stringify({ error: "invalid JSON body" }));
+  }
+}
+
+export async function handleChatReact(req, res, reqUrl) {
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const store = getStorage();
+    const room = normalizeRoomName(body.room || reqUrl.searchParams.get("room") || "general");
+    const messageId = String(body.messageId || "").trim();
+    const emoji = String(body.emoji || "").trim().slice(0, 8);
+    if (!messageId || !emoji) {
+      res.writeHead(400, { "content-type": "application/json" });
+      return res.end(JSON.stringify({ error: "messageId and emoji are required" }));
+    }
+    const authRes = await resolveChatAuth(req, body);
+    if (!authRes.ok) {
+      res.writeHead(authRes.status || 403, { "content-type": "application/json" });
+      return res.end(JSON.stringify({ error: authRes.error, reason: authRes.reason }));
+    }
+    const auth = authRes.auth;
+    const existing = materializeChatMessages(store.readChatEntries(), room);
+    const parent = existing.find((m) => m.id === messageId);
+    if (!parent) {
+      res.writeHead(404, { "content-type": "application/json" });
+      return res.end(JSON.stringify({ error: "message not found in this room" }));
+    }
+    const evt = {
+      id: `react_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      type: "reaction", room, messageId, emoji,
+      agentId: auth.id, agentName: auth.name, ts: new Date().toISOString(),
+    };
+    store.appendChat(evt);
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, reaction: evt }));
+  } catch {
+    res.writeHead(400, { "content-type": "application/json" });
+    return res.end(JSON.stringify({ error: "invalid JSON body" }));
+  }
+}

package/src/server/routes/clawbots.mjs

@@ -0,0 +1,182 @@
+/**
+ * Routes: /api/clawbots/*, /api/invites/*
+ */
+
+import fs from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { CLAWBOTS_PATH } from "../../lib/paths.mjs";
+import { verifyClawbot, registerClawbot } from "../../lib/clawbots.mjs";
+import { getStorage } from "../storage/index.mjs";
+import { getRegistrationKey } from "../middleware/auth.mjs";
+import { collectBody } from "../middleware/body-limit.mjs";
+
+const OPEN_REGISTRATION = /^(1|true|yes|on)$/i.test(String(process.env.APE_CLAW_OPEN_REGISTRATION || "").trim());
+const REGISTRATION_COOLDOWN_MS = Math.max(0, Number(process.env.APE_CLAW_REGISTRATION_COOLDOWN_MS || 10000));
+const INVITE_TTL_MS = Math.max(60_000, Number(process.env.APE_CLAW_INVITE_TTL_MS || 24 * 60 * 60 * 1000));
+const INVITE_MAX_USES = Math.max(1, Number(process.env.APE_CLAW_INVITE_MAX_USES || 5));
+const registrationByIp = new Map();
+
+function sha256(input) { return createHash("sha256").update(String(input)).digest("hex"); }
+
+function clientIpFromReq(req) {
+  const xff = String(req.headers["x-forwarded-for"] || "").trim();
+  if (xff) return xff.split(",")[0].trim();
+  return String(req.socket?.remoteAddress || "").trim() || "unknown";
+}
+
+function mintInvite({ ttlMs = INVITE_TTL_MS, uses = 1 } = {}) {
+  const store = getStorage();
+  const safeUses = Math.max(1, Math.min(INVITE_MAX_USES, Number(uses) || 1));
+  const safeTtl = Math.max(60_000, Math.min(7 * 24 * 60 * 60 * 1000, Number(ttlMs) || INVITE_TTL_MS));
+  const token = `inv_${randomUUID().replace(/-/g, "")}`;
+  const tokenHash = sha256(token);
+  const now = Date.now();
+  const invites = store.readInvites();
+  invites.invites[tokenHash] = {
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + safeTtl).toISOString(),
+    usesRemaining: safeUses,
+  };
+  store.writeInvites(invites);
+  return { token, tokenHash, expiresAt: invites.invites[tokenHash].expiresAt, usesRemaining: safeUses };
+}
+
+function consumeInvite(inviteToken) {
+  const store = getStorage();
+  const token = String(inviteToken || "").trim();
+  if (!token) return { ok: false, reason: "missing invite" };
+  const tokenHash = sha256(token);
+  const invites = store.readInvites();
+  const row = invites.invites?.[tokenHash];
+  if (!row) return { ok: false, reason: "invite not found" };
+  const now = Date.now();
+  const exp = new Date(row.expiresAt || 0).getTime();
+  if (!exp || exp <= now) return { ok: false, reason: "invite expired" };
+  const remaining = Number(row.usesRemaining || 0);
+  if (remaining <= 0) return { ok: false, reason: "invite exhausted" };
+  invites.invites[tokenHash] = { ...row, usesRemaining: remaining - 1, lastUsedAt: new Date(now).toISOString() };
+  store.writeInvites(invites);
+  return { ok: true };
+}
+
+export function handleClawbotsList(req, res) {
+  if (!fs.existsSync(CLAWBOTS_PATH)) {
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ count: 0, clawbots: [], sharedKeyConfigured: false }));
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(CLAWBOTS_PATH, "utf8"));
+    const agents = raw.agents || {};
+    const clawbots = Object.entries(agents).map(([id, a]) => ({
+      agentId: id, name: a.name || id, enabled: a.enabled !== false, createdAt: a.createdAt || null,
+    }));
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    const sharedKeyConfigured = Boolean(raw.sharedOpenseaApiKey || process.env.APE_CLAW_SHARED_OPENSEA_KEY);
+    return res.end(JSON.stringify({ count: clawbots.length, clawbots, sharedKeyConfigured }));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+export function handleClawbotsVerify(req, res) {
+  const headerAgentId = String(req.headers["x-agent-id"] || "").trim();
+  const headerAgentToken = String(req.headers["x-agent-token"] || "").trim();
+  if (!headerAgentId || !headerAgentToken) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "missing credentials: x-agent-id + x-agent-token are required" }));
+  }
+  const verification = verifyClawbot({ agentId: headerAgentId, agentToken: headerAgentToken });
+  if (!verification.verified) {
+    res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "not verified", reason: verification.reason }));
+  }
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({
+    ok: true, verified: true, agent: verification.agent, sharedOpenseaApiKey: verification.sharedOpenseaApiKey || "",
+  }));
+}
+
+export async function handleInviteCreate(req, res) {
+  const REGISTRATION_KEY = getRegistrationKey();
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    if (!REGISTRATION_KEY) {
+      res.writeHead(503, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "invite creation disabled: backend missing APE_CLAW_REGISTRATION_KEY" }));
+    }
+    const providedKey = String(req.headers["x-registration-key"] || "").trim();
+    if (!providedKey || providedKey !== REGISTRATION_KEY) {
+      res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "invalid registration key" }));
+    }
+    const invite = mintInvite({ ttlMs: body?.ttlMs, uses: body?.uses });
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({
+      ok: true, invite: invite.token, expiresAt: invite.expiresAt, usesRemaining: invite.usesRemaining,
+      note: "Share this invite privately. It can be redeemed via clawbot register --invite <token>.",
+    }));
+  } catch {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "invalid JSON body" }));
+  }
+}
+
+export async function handleClawbotsRegister(req, res) {
+  const REGISTRATION_KEY = getRegistrationKey();
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const inviteToken = String(body?.invite || "").trim();
+    const inviteOk = inviteToken ? consumeInvite(inviteToken) : { ok: false, reason: "missing invite" };
+
+    if (!REGISTRATION_KEY && !OPEN_REGISTRATION && !inviteOk.ok) {
+      res.writeHead(503, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "registration is disabled: use an invite, set APE_CLAW_REGISTRATION_KEY, or enable APE_CLAW_OPEN_REGISTRATION" }));
+    }
+    const hasValidKey = (() => {
+      if (!REGISTRATION_KEY) return false;
+      const providedKey = String(req.headers["x-registration-key"] || "").trim();
+      return Boolean(providedKey) && providedKey === REGISTRATION_KEY;
+    })();
+    if (!OPEN_REGISTRATION && !hasValidKey && !inviteOk.ok) {
+      res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "registration not allowed (missing invite or invalid registration key)" }));
+    }
+    if (OPEN_REGISTRATION && !hasValidKey && REGISTRATION_COOLDOWN_MS > 0) {
+      const ip = clientIpFromReq(req);
+      const now = Date.now();
+      const last = Number(registrationByIp.get(ip) || 0);
+      if (last && now - last < REGISTRATION_COOLDOWN_MS) {
+        const waitMs = REGISTRATION_COOLDOWN_MS - (now - last);
+        res.writeHead(429, { "content-type": "application/json; charset=utf-8" });
+        return res.end(JSON.stringify({ error: "registration rate limited", retryAfterMs: waitMs }));
+      }
+      registrationByIp.set(ip, now);
+    }
+
+    const agentId = String(body?.agentId || "").trim();
+    const displayName = String(body?.name || agentId || "").trim();
+    if (!agentId) {
+      res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "agentId is required" }));
+    }
+    try {
+      const reg = registerClawbot({ agentId, displayName });
+      res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({
+        registered: true, agentId: reg.agentId, name: reg.displayName, token: reg.token,
+        note: "Save this token — it is shown only once. Use as APE_CLAW_AGENT_TOKEN or --agent-token.",
+      }));
+    } catch (err) {
+      res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: err.message || "registration failed" }));
+    }
+  } catch {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "invalid JSON body" }));
+  }
+}

package/src/server/routes/events.mjs

@@ -0,0 +1,95 @@
+/**
+ * Routes: /events (SSE), /events/backlog, POST /api/events
+ */
+
+import { verifyClawbot } from "../../lib/clawbots.mjs";
+import { getStorage } from "../storage/index.mjs";
+import { addTelemetryClient, nextEventId } from "../sse.mjs";
+import { collectBody } from "../middleware/body-limit.mjs";
+
+export function handleEventsSse(req, res) {
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+  });
+  res.write("\n");
+
+  const lastEventId = req.headers["last-event-id"];
+  if (lastEventId) {
+    const store = getStorage();
+    const backlog = store.getEventBacklog(300);
+    for (const evt of backlog) {
+      const id = nextEventId();
+      res.write(`id: ${id}\ndata: ${JSON.stringify(evt)}\n\n`);
+    }
+  }
+
+  const remove = addTelemetryClient(res);
+  req.on("close", remove);
+}
+
+export function handleEventsBacklog(req, res, reqUrl) {
+  const store = getStorage();
+  const limit = Math.max(1, Math.min(1000, Number(reqUrl?.searchParams?.get("limit") || 300)));
+  const since = reqUrl?.searchParams?.get("since") || "";
+  let events = store.getEventBacklog(limit);
+  if (since) {
+    events = events.filter((e) => e.ts > since);
+  }
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify({ events }));
+}
+
+export async function handlePostEvent(req, res) {
+  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; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "invalid JSON body" }));
+  }
+
+  const eventType = String(body?.eventType || "").trim();
+  if (!eventType) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "eventType is required" }));
+  }
+
+  const headerAgentId = String(req.headers["x-agent-id"] || "").trim();
+  const headerAgentToken = String(req.headers["x-agent-token"] || "").trim();
+  if (!headerAgentId || !headerAgentToken) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "missing credentials: x-agent-id + x-agent-token are required" }));
+  }
+  const verification = verifyClawbot({ agentId: headerAgentId, agentToken: headerAgentToken });
+  if (!verification.verified) {
+    res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "not verified", reason: verification.reason }));
+  }
+
+  const evt = {
+    v: Number(body?.v || 1),
+    ts: typeof body?.ts === "string" ? body.ts
+      : (typeof body?.ts === "number" && Number.isFinite(body.ts)) ? new Date(body.ts * 1000).toISOString()
+        : new Date().toISOString(),
+    eventType,
+    agentId: headerAgentId,
+    sessionId: String(body?.sessionId || "remote-session"),
+    traceId: String(body?.traceId || `trace_${Date.now()}`),
+    command: String(body?.command || ""),
+    dryRun: Boolean(body?.dryRun),
+    chainId: Number(body?.chainId || 33139),
+    payload: (body?.payload || body?.data) && typeof (body?.payload || body?.data) === "object" ? (body?.payload || body?.data) : {},
+    result: body?.result && typeof body.result === "object" ? body.result : {},
+    ok: body?.ok !== false,
+    error: body?.error || null,
+    ...(body?.source ? { source: String(body.source) } : {}),
+  };
+
+  const store = getStorage();
+  store.appendEvent(evt);
+
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: true, event: evt }));
+}

package/src/server/routes/health.mjs

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import { EVENTS_PATH, CHAT_PATH, POLICY_PATH, ALLOWLIST_PATH, CLAWBOTS_PATH, INVITES_PATH } from "../../lib/paths.mjs";
+import { getStorage } from "../storage/index.mjs";
+import { getRegistrationKey, getMoltbookAppKey, getMoltbookApiBase } from "../middleware/auth.mjs";
+
+const PORT = Number(process.env.APE_CLAW_UI_PORT || 8787);
+const ROOT = (await import("../../lib/paths.mjs")).ROOT;
+const OPEN_REGISTRATION = /^(1|true|yes|on)$/i.test(String(process.env.APE_CLAW_OPEN_REGISTRATION || "").trim());
+const REGISTRATION_COOLDOWN_MS = Math.max(0, Number(process.env.APE_CLAW_REGISTRATION_COOLDOWN_MS || 10000));
+const INVITE_TTL_MS = Math.max(60_000, Number(process.env.APE_CLAW_INVITE_TTL_MS || 24 * 60 * 60 * 1000));
+const INVITE_MAX_USES = Math.max(1, Number(process.env.APE_CLAW_INVITE_MAX_USES || 5));
+
+function resolveV2ReceiptReadConfig() {
+  const store = getStorage();
+  const fromEnvRpc = String(process.env.APE_CLAW_V2_RPC_URL || process.env.RPC_URL_33139 || "").trim();
+  const fromEnvReceipts = String(process.env.APE_CLAW_V2_RECEIPT_REGISTRY || "").trim();
+  const rec = store.resolveV2DeploymentRecord();
+  const receiptsAddress = fromEnvReceipts || String(rec?.receipts || "").trim();
+  let rpcUrl = fromEnvRpc;
+  let inferredRpc = false;
+  if (!rpcUrl && rec && Number(rec.chainId) === 31337) {
+    rpcUrl = "http://127.0.0.1:8545";
+    inferredRpc = true;
+  }
+  if (!rpcUrl || !receiptsAddress) {
+    return { ok: false, rpcUrl: rpcUrl || "", receiptsAddress: receiptsAddress || "", inferredRpc, reason: "missing v2 config" };
+  }
+  return { ok: true, rpcUrl, receiptsAddress, inferredRpc };
+}
+
+export { resolveV2ReceiptReadConfig };
+
+export function handleHealth(req, res) {
+  const store = getStorage();
+  const v2Cfg = resolveV2ReceiptReadConfig();
+  const skillcardsUserIndexPath = store.SKILLCARDS_USER_DIR
+    ? `${store.SKILLCARDS_USER_DIR}/index.json`
+    : "";
+  const payload = {
+    ok: true,
+    service: "ape-claw-telemetry",
+    port: PORT,
+    root: ROOT,
+    paths: {
+      events: EVENTS_PATH, chat: CHAT_PATH, policy: POLICY_PATH,
+      allowlist: ALLOWLIST_PATH, clawbots: CLAWBOTS_PATH, invites: INVITES_PATH,
+      skillcardsUserIndex: skillcardsUserIndexPath,
+    },
+    counts: {
+      eventsBytes: fs.existsSync(EVENTS_PATH) ? fs.statSync(EVENTS_PATH).size : 0,
+      chatBytes: fs.existsSync(CHAT_PATH) ? fs.statSync(CHAT_PATH).size : 0,
+    },
+    identity: {
+      moltbookEnabled: Boolean(getMoltbookAppKey()),
+      moltbookApiBase: getMoltbookApiBase(),
+      registrationEnabled: Boolean(getRegistrationKey()),
+      openRegistration: OPEN_REGISTRATION,
+      registrationCooldownMs: REGISTRATION_COOLDOWN_MS,
+      inviteTtlMs: INVITE_TTL_MS,
+      inviteMaxUses: INVITE_MAX_USES,
+    },
+    v2: {
+      rpcUrl: v2Cfg.ok ? v2Cfg.rpcUrl : (v2Cfg.rpcUrl || null),
+      receiptRegistry: v2Cfg.ok ? v2Cfg.receiptsAddress : (v2Cfg.receiptsAddress || null),
+      inferredRpc: Boolean(v2Cfg.inferredRpc),
+      configured: Boolean(v2Cfg.ok),
+    },
+    ts: new Date().toISOString(),
+  };
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify(payload));
+}

package/src/server/routes/pod.mjs

@@ -0,0 +1,64 @@
+/**
+ * Routes: /api/pod/*
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "../../lib/io.mjs";
+import { getStorage } from "../storage/index.mjs";
+import { requireSkillWriteAuth } from "../middleware/auth.mjs";
+
+function getPodStatus() {
+  const store = getStorage();
+  const workspacePath = store.findPodWorkspaceDir();
+  if (!workspacePath) return { ok: true, status: "not-initialized", workspacePath: null };
+
+  const agentsMdPath = path.join(workspacePath, "AGENTS.md");
+  const tasksPath = path.join(workspacePath, "memory", "active-tasks.md");
+  const stopFlagPath = path.join(workspacePath, "stop.flag");
+  const heartbeatPath = path.join(workspacePath, "state", "last-heartbeat.json");
+
+  const hasAgentsMd = fs.existsSync(agentsMdPath);
+  const hasTasks = fs.existsSync(tasksPath);
+  const stopped = fs.existsSync(stopFlagPath);
+
+  let lastHeartbeat = null;
+  if (fs.existsSync(heartbeatPath)) {
+    try { lastHeartbeat = JSON.parse(fs.readFileSync(heartbeatPath, "utf8"))?.timestamp || null; } catch {}
+  }
+
+  return {
+    ok: true,
+    status: hasAgentsMd ? (stopped ? "stopped" : "running") : "not-initialized",
+    workspacePath, hasAgentsMd, hasTasks, stopped, lastHeartbeat,
+  };
+}
+
+export function handlePodStatus(req, res) {
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify(getPodStatus()));
+}
+
+export function handlePodStop(req, res) {
+  const auth = requireSkillWriteAuth(req);
+  if (!auth.ok) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "unauthorized (set x-registration-key or x-agent-id/x-agent-token)" }));
+  }
+  const store = getStorage();
+  const workspacePath = store.findPodWorkspaceDir();
+  if (!workspacePath) {
+    res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "pod workspace not found" }));
+  }
+  try {
+    ensureDir(workspacePath);
+    const stopFlagPath = path.join(workspacePath, "stop.flag");
+    fs.writeFileSync(stopFlagPath, new Date().toISOString() + "\n");
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, action: "stop", flagPath: stopFlagPath }));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "failed to create stop flag" }));
+  }
+}