clawmatrix 0.1.14 → 0.1.16

package/src/web.ts

@@ -1,22 +1,120 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { PeerManager } from "./peer-manager.ts";
+import type { HandoffManager } from "./handoff.ts";
 import type { ClawMatrixConfig } from "./config.ts";
+import type { SatelliteContext, IngestedEvent } from "./types.ts";
 import { timingSafeEqual } from "./auth.ts";
 import { renderDashboard } from "./web-ui.ts";
+import { readBody } from "./http-utils.ts";
 
 const COOKIE_NAME = "clawmatrix_token";
 const SESSION_MAX_AGE = 86400 * 7; // 7 days
+const MAX_EVENTS = 100; // ring buffer for satellite polling
+const LOGIN_RATE_WINDOW = 60_000; // 1 minute
+const LOGIN_RATE_MAX = 10; // max attempts per window per IP
+const MAX_INGESTED_EVENTS = 500; // ring buffer for ingested events
+const INGESTED_EVENT_TTL = 86400_000; // 24 hours
+const SATELLITE_TOOL_TIMEOUT = 120_000; // 2 min timeout for satellite tool requests
+
+interface SatelliteEvent {
+  ts: number;
+  type: "peer_online" | "peer_offline" | "handoff_done" | "context_update" | "event_ingested";
+  data: Record<string, unknown>;
+}
+
+interface PendingSatelliteTool {
+  id: string;
+  tool: string;
+  params: Record<string, unknown>;
+  from: string;
+  ts: number;
+  resolve: (result: Record<string, unknown>) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
 
 export class WebHandler {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
+  private handoffManager: HandoffManager;
   private token: string;
   private startTime = Date.now();
-
-  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+  private satelliteEvents: SatelliteEvent[] = [];
+  private satelliteContexts = new Map<string, SatelliteContext>(); // nodeId → context
+  private knownPeerState = new Map<string, boolean>(); // nodeId → online
+  private satelliteToolQueue = new Map<string, PendingSatelliteTool[]>(); // nodeId → pending tools
+  private ingestedEvents: IngestedEvent[] = []; // ring buffer for ingested events
+  private loginAttempts = new Map<string, { count: number; resetAt: number }>(); // IP → rate limit
+  private loginCleanupTimer: ReturnType<typeof setInterval> | null = null;
+  private onPeerConnected: (nodeId: string) => void;
+  private onPeerDisconnected: (nodeId: string) => void;
+
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager, handoffManager: HandoffManager) {
     this.config = config;
     this.peerManager = peerManager;
+    this.handoffManager = handoffManager;
     this.token = config.web!.token;
+
+    // Periodically clean up stale login rate-limit entries
+    this.loginCleanupTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [ip, entry] of this.loginAttempts) {
+        if (now > entry.resetAt) this.loginAttempts.delete(ip);
+      }
+    }, LOGIN_RATE_WINDOW);
+
+    // Listen for peer changes in real-time and push satellite events immediately
+    this.onPeerConnected = (nodeId: string) => {
+      const route = peerManager.router.getRoute(nodeId);
+      this.pushSatelliteEvent({
+        ts: Date.now(),
+        type: "peer_online",
+        data: {
+          nodeId,
+          agents: route?.agents.map(a => a.id) ?? [],
+          models: route?.models.map(m => m.id) ?? [],
+        },
+      });
+      this.knownPeerState.set(nodeId, true);
+    };
+
+    this.onPeerDisconnected = (nodeId: string) => {
+      this.pushSatelliteEvent({
+        ts: Date.now(),
+        type: "peer_offline",
+        data: { nodeId },
+      });
+      this.knownPeerState.set(nodeId, false);
+    };
+
+    peerManager.on("peerConnected", this.onPeerConnected);
+    peerManager.on("peerDisconnected", this.onPeerDisconnected);
+  }
+
+  /** Clean up timers and pending requests on shutdown. */
+  destroy() {
+    // Remove event listeners to prevent post-destroy callbacks
+    this.peerManager.removeListener("peerConnected", this.onPeerConnected);
+    this.peerManager.removeListener("peerDisconnected", this.onPeerDisconnected);
+
+    if (this.loginCleanupTimer) {
+      clearInterval(this.loginCleanupTimer);
+      this.loginCleanupTimer = null;
+    }
+    // Clear all satellite tool timeouts
+    for (const [, queue] of this.satelliteToolQueue) {
+      for (const entry of queue) {
+        clearTimeout(entry.timer);
+        entry.reject(new Error("Shutting down"));
+      }
+    }
+    this.satelliteToolQueue.clear();
+    // Clear long-poll waiters
+    for (const w of this.satelliteWaiters) {
+      clearTimeout(w.timer);
+      try { w.res.end(); } catch { /* already closed */ }
+    }
+    this.satelliteWaiters.length = 0;
   }
 
   /** Handle an HTTP request. Returns true if handled, false to fall through. */
@@ -37,46 +135,84 @@ export class WebHandler {
       return true;
     }
 
-    // All /api/* routes require auth
+    // All /api/* routes require auth (async)
     if (path.startsWith("/api/")) {
-      if (!this.checkAuth(req)) {
-        res.writeHead(401, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Unauthorized" }));
-        return true;
-      }
+      this.handleAuthenticatedRoute(req, res, path);
+      return true;
+    }
 
-      if (path === "/api/status" && req.method === "GET") {
-        this.handleStatus(res);
-        return true;
-      }
+    return false;
+  }
 
-      if (path === "/api/chat" && req.method === "POST") {
-        this.handleChat(req, res);
-        return true;
-      }
+  private async handleAuthenticatedRoute(req: IncomingMessage, res: ServerResponse, path: string) {
+    if (!await this.checkAuth(req)) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized" }));
+      return;
+    }
 
-      if (path === "/api/logout" && req.method === "POST") {
-        res.writeHead(200, {
-          "Content-Type": "application/json",
-          "Set-Cookie": `${COOKIE_NAME}=; Path=/; Max-Age=0; HttpOnly; SameSite=Strict`,
+    if (path === "/api/status" && req.method === "GET") {
+      this.handleStatus(res);
+      return;
+    }
 
-        });
-        res.end(JSON.stringify({ ok: true }));
-        return true;
-      }
+    if (path === "/api/chat" && req.method === "POST") {
+      this.handleChat(req, res);
+      return;
+    }
 
-      res.writeHead(404, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "Not found" }));
-      return true;
+    if (path === "/api/handoff" && req.method === "POST") {
+      this.handleHandoff(req, res);
+      return;
     }
 
-    return false;
+    if (path === "/api/events/ingest" && req.method === "POST") {
+      this.handleEventIngest(req, res);
+      return;
+    }
+
+    if (path === "/api/events" && req.method === "GET") {
+      this.handleEventQuery(req, res);
+      return;
+    }
+
+    if (path === "/api/events/consume" && req.method === "POST") {
+      this.handleEventConsume(req, res);
+      return;
+    }
+
+    if (path === "/api/satellite/poll" && req.method === "GET") {
+      this.handleSatellitePoll(req, res);
+      return;
+    }
+
+    if (path === "/api/satellite/context" && req.method === "POST") {
+      this.handleSatelliteContext(req, res);
+      return;
+    }
+
+    if (path === "/api/satellite/tool/result" && req.method === "POST") {
+      this.handleSatelliteToolResult(req, res);
+      return;
+    }
+
+    if (path === "/api/logout" && req.method === "POST") {
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Set-Cookie": `${COOKIE_NAME}=; Path=/; Max-Age=0; HttpOnly; SameSite=Strict`,
+      });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
   }
 
-  private checkAuth(req: IncomingMessage): boolean {
+  private async checkAuth(req: IncomingMessage): Promise<boolean> {
     // Check Authorization header
     const authHeader = req.headers.authorization;
-    if (authHeader?.startsWith("Bearer ") && timingSafeEqual(authHeader.slice(7), this.token)) {
+    if (authHeader?.startsWith("Bearer ") && await timingSafeEqual(authHeader.slice(7), this.token)) {
       return true;
     }
 
@@ -84,7 +220,8 @@ export class WebHandler {
     const cookies = req.headers.cookie ?? "";
     const match = cookies.split(";").find((c) => c.trim().startsWith(`${COOKIE_NAME}=`));
     if (match) {
-      const value = match.trim().slice(COOKIE_NAME.length + 1);
+      const raw = match.trim().slice(COOKIE_NAME.length + 1);
+      const value = decodeURIComponent(raw);
       return timingSafeEqual(value, this.token);
     }
 
@@ -92,19 +229,40 @@ export class WebHandler {
   }
 
   private async handleLogin(req: IncomingMessage, res: ServerResponse) {
+    // Rate limiting by IP
+    const ip = req.socket.remoteAddress ?? "unknown";
+    const now = Date.now();
+    let entry = this.loginAttempts.get(ip);
+    if (entry && now > entry.resetAt) entry = undefined;
+    if (entry && entry.count >= LOGIN_RATE_MAX) {
+      res.writeHead(429, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Too many login attempts, try again later" }));
+      return;
+    }
+
     try {
       const body = await readBody(req);
       const { token } = JSON.parse(body);
 
-      if (!token || !timingSafeEqual(String(token), this.token)) {
+      if (!token || !await timingSafeEqual(String(token), this.token)) {
+        // Track failed attempt
+        if (!entry) {
+          entry = { count: 0, resetAt: now + LOGIN_RATE_WINDOW };
+          this.loginAttempts.set(ip, entry);
+        }
+        entry.count++;
+
         res.writeHead(403, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Invalid token" }));
         return;
       }
 
+      // Success — clear rate limit for this IP
+      this.loginAttempts.delete(ip);
+
       res.writeHead(200, {
         "Content-Type": "application/json",
-        "Set-Cookie": `${COOKIE_NAME}=${token}; Path=/; Max-Age=${SESSION_MAX_AGE}; HttpOnly; SameSite=Strict`,
+        "Set-Cookie": `${COOKIE_NAME}=${encodeURIComponent(token)}; Path=/; Max-Age=${SESSION_MAX_AGE}; HttpOnly; SameSite=Strict`,
       });
       res.end(JSON.stringify({ ok: true }));
     } catch {
@@ -122,9 +280,25 @@ export class WebHandler {
       tags: this.config.tags,
       connection: "self" as const,
       online: true,
+      deviceInfo: this.peerManager.localDeviceInfo,
+      toolProxy: this.config.toolProxy ? {
+        enabled: this.config.toolProxy.enabled,
+        allow: this.config.toolProxy.allow,
+        deny: this.config.toolProxy.deny,
+      } : undefined,
+      clusterTools: [
+        "cluster_handoff", "cluster_send", "cluster_peers",
+        "cluster_exec", "cluster_read", "cluster_write", "cluster_tool",
+      ],
     };
 
-    const peerNodes = peers.map((p) => ({
+    // All mesh peers share these cluster tools (they all run the ClawMatrix plugin)
+    const CLUSTER_TOOLS = [
+      "cluster_handoff", "cluster_send", "cluster_peers",
+      "cluster_exec", "cluster_read", "cluster_write", "cluster_tool",
+    ];
+
+    const peerNodes: Record<string, unknown>[] = peers.map((p) => ({
       nodeId: p.nodeId,
       agents: p.agents,
       models: p.models,
@@ -134,8 +308,40 @@ export class WebHandler {
       online: this.peerManager.canReach(p.nodeId),
       lastSeen: p.lastSeen,
       latencyMs: p.latencyMs,
+      directPeers: p.directPeers.length > 0 ? p.directPeers : undefined,
+      deviceInfo: p.deviceInfo,
+      toolProxy: p.toolProxy,
+      clusterTools: CLUSTER_TOOLS,
     }));
 
+    // Merge satellite nodes into peers list
+    for (const sat of this.getSatelliteContexts()) {
+      peerNodes.push({
+        nodeId: sat.nodeId,
+        agents: [],
+        models: [],
+        tags: [],
+        connection: "satellite" as const,
+        online: true,
+        toolProxy: sat.tools?.length ? {
+          enabled: true,
+          allow: sat.tools,
+          deny: [],
+        } : undefined,
+        // Satellite-specific fields
+        ssid: sat.ssid,
+        ip: sat.ip,
+        router: sat.router,
+        cellular: sat.cellular,
+        country: sat.country,
+        battery: sat.battery,
+        charging: sat.charging,
+        platform: sat.platform,
+        location: sat.location,
+        lastSeen: sat.ts,
+      });
+    }
+
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({
       nodeId: this.config.nodeId,
@@ -207,24 +413,494 @@ export class WebHandler {
       }
     }
   }
-}
+  private async handleHandoff(req: IncomingMessage, res: ServerResponse) {
+    try {
+      const body = await readBody(req);
+      const { nodeId, agent, task } = JSON.parse(body);
 
-const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
-
-function readBody(req: IncomingMessage): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    let size = 0;
-    req.on("data", (chunk: Buffer) => {
-      size += chunk.length;
-      if (size > MAX_BODY_SIZE) {
-        req.destroy();
-        reject(new Error("Request body too large"));
+      if (!nodeId || !agent || !task) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "nodeId, agent and task required" }));
         return;
       }
-      chunks.push(chunk);
+
+      // SSE headers
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+      });
+
+      let closed = false;
+      req.on("close", () => { closed = true; });
+
+      const result = await this.handoffManager.handoff(agent, task, undefined, {
+        nodeId,
+        onStream: (delta) => {
+          if (closed) return;
+          res.write(`data: ${JSON.stringify({ type: "delta", content: delta })}\n\n`);
+        },
+      });
+
+      if (!closed) {
+        res.write(`data: ${JSON.stringify({ type: "done", ...result })}\n\n`);
+      }
+      res.end();
+    } catch (err) {
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Internal error" }));
+      } else {
+        res.write(`data: ${JSON.stringify({ type: "error", error: err instanceof Error ? err.message : "Internal error" })}\n\n`);
+        res.end();
+      }
+    }
+  }
+  // ── Satellite integration ────────────────────────────────────────
+
+  /** Sync knownPeerState with current routes (no event emission — events come from real-time listeners). */
+  private syncPeerState() {
+    const peers = this.peerManager.router.getAllPeers();
+    for (const p of peers) {
+      const online = this.peerManager.canReach(p.nodeId);
+      this.knownPeerState.set(p.nodeId, online);
+    }
+    // Remove peers no longer in routes
+    for (const [nodeId] of this.knownPeerState) {
+      if (!peers.some(p => p.nodeId === nodeId)) {
+        this.knownPeerState.delete(nodeId);
+      }
+    }
+  }
+
+  private pushSatelliteEvent(event: SatelliteEvent) {
+    this.satelliteEvents.push(event);
+    if (this.satelliteEvents.length > MAX_EVENTS) {
+      this.satelliteEvents.splice(0, this.satelliteEvents.length - MAX_EVENTS);
+    }
+    // Wake up any long-polling clients immediately
+    if (this.satelliteWaiters.length > 0) {
+      this.flushSatelliteWaiters();
+    }
+  }
+
+  /** Notify satellite of handoff completion. Called externally. */
+  notifyHandoffDone(nodeId: string, agent: string, success: boolean, summary?: string) {
+    this.pushSatelliteEvent({
+      ts: Date.now(),
+      type: "handoff_done",
+      data: { nodeId, agent, success, summary },
+    });
+  }
+
+  /** Pending long-poll waiters. */
+  private satelliteWaiters: Array<{ res: ServerResponse; since: number; nodeId?: string; timer: ReturnType<typeof setTimeout> }> = [];
+
+  /** GET /api/satellite/poll?since=<ts>&wait=<seconds>&nodeId=<id> — poll with optional long-poll */
+  private handleSatellitePoll(req: IncomingMessage, res: ServerResponse) {
+    this.syncPeerState();
+
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const since = parseInt(url.searchParams.get("since") ?? "0", 10) || 0;
+    const wait = Math.min(Math.max(parseInt(url.searchParams.get("wait") ?? "0", 10) || 0, 0), 55);
+    const nodeId = url.searchParams.get("nodeId") || undefined;
+
+    const events = this.satelliteEvents.filter(e => e.ts > since);
+    const hasPendingTools = nodeId ? (this.satelliteToolQueue.get(nodeId)?.length ?? 0) > 0 : false;
+
+    // If there are already events/tools or no wait requested, respond immediately
+    if (events.length > 0 || hasPendingTools || wait === 0) {
+      this.sendSatellitePollResponse(res, since, nodeId);
+      return;
+    }
+
+    // Long poll: hold the connection until events arrive or timeout
+    const timer = setTimeout(() => {
+      this.removeSatelliteWaiter(res);
+      this.sendSatellitePollResponse(res, since, nodeId);
+    }, wait * 1000);
+
+    this.satelliteWaiters.push({ res, since, nodeId, timer });
+
+    // If client disconnects, clean up
+    req.on("close", () => {
+      this.removeSatelliteWaiter(res);
+      clearTimeout(timer);
     });
-    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
-    req.on("error", reject);
-  });
+  }
+
+  /** Flush all waiting long-poll clients (called when new events are pushed). */
+  private flushSatelliteWaiters(targetNodeId?: string) {
+    if (targetNodeId) {
+      // Only flush waiters for this specific satellite node
+      const toFlush: typeof this.satelliteWaiters = [];
+      this.satelliteWaiters = this.satelliteWaiters.filter(w => {
+        if (w.nodeId === targetNodeId) {
+          toFlush.push(w);
+          return false;
+        }
+        return true;
+      });
+      for (const w of toFlush) {
+        clearTimeout(w.timer);
+        this.sendSatellitePollResponse(w.res, w.since, w.nodeId);
+      }
+    } else {
+      const waiters = this.satelliteWaiters.splice(0);
+      for (const w of waiters) {
+        clearTimeout(w.timer);
+        this.sendSatellitePollResponse(w.res, w.since, w.nodeId);
+      }
+    }
+  }
+
+  private removeSatelliteWaiter(res: ServerResponse) {
+    const idx = this.satelliteWaiters.findIndex(w => w.res === res);
+    if (idx >= 0) this.satelliteWaiters.splice(idx, 1);
+  }
+
+  private sendSatellitePollResponse(res: ServerResponse, since: number, satelliteNodeId?: string) {
+    this.syncPeerState();
+    const peers = this.peerManager.router.getAllPeers();
+    const events = this.satelliteEvents.filter(e => e.ts > since);
+
+    // Include pending tool requests for this satellite node
+    let pendingTools: Array<{ id: string; tool: string; params: Record<string, unknown> }> | undefined;
+    if (satelliteNodeId) {
+      const queue = this.satelliteToolQueue.get(satelliteNodeId);
+      if (queue && queue.length > 0) {
+        pendingTools = queue.map(t => ({ id: t.id, tool: t.tool, params: t.params }));
+      }
+    }
+
+    // Merge satellite nodes into peers list
+    const allPeers: Record<string, unknown>[] = peers.map(p => ({
+      nodeId: p.nodeId,
+      online: this.peerManager.canReach(p.nodeId),
+      agents: p.agents.map(a => a.id),
+      models: p.models.map(m => m.id),
+      tags: p.tags,
+      latencyMs: p.latencyMs,
+      connection: p.connection ? "direct" : "relay",
+    }));
+
+    for (const sat of this.getSatelliteContexts()) {
+      allPeers.push({
+        nodeId: sat.nodeId,
+        online: true,
+        agents: [],
+        models: [],
+        tags: [],
+        connection: "satellite",
+        tools: sat.tools ?? [],
+      });
+    }
+
+    const status = {
+      nodeId: this.config.nodeId,
+      uptime: Math.floor((Date.now() - this.startTime) / 1000),
+      peers: allPeers,
+      events,
+      pendingTools,
+      ts: Date.now(),
+    };
+
+    try {
+      if (res.writableEnded) return;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(status));
+    } catch {
+      // Client already disconnected
+    }
+  }
+
+  /** POST /api/satellite/context — receive network context from satellite */
+  private async handleSatelliteContext(req: IncomingMessage, res: ServerResponse) {
+    try {
+      const body = await readBody(req);
+      const ctx = JSON.parse(body);
+
+      const satCtx: SatelliteContext = {
+        nodeId: ctx.nodeId || "unknown",
+        ssid: ctx.ssid || undefined,
+        ip: ctx.ip || undefined,
+        router: ctx.router || undefined,
+        cellular: !ctx.ssid,
+        country: ctx.country || undefined,
+        tools: Array.isArray(ctx.tools) ? ctx.tools : undefined,
+        ts: Date.now(),
+        // Extended context
+        battery: typeof ctx.battery === "number" ? ctx.battery : undefined,
+        charging: typeof ctx.charging === "boolean" ? ctx.charging : undefined,
+        platform: ctx.platform || undefined,
+        location: ctx.location || undefined,
+      };
+
+      this.satelliteContexts.set(satCtx.nodeId, satCtx);
+
+      // Propagate to PeerManager so it gets gossiped to all mesh nodes
+      this.peerManager.satelliteContexts = this.getSatelliteContexts();
+
+      this.pushSatelliteEvent({
+        ts: Date.now(),
+        type: "context_update",
+        data: { ...satCtx },
+      });
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  // ── Satellite tool proxy ────────────────────────────────────────
+
+  /** Check if a nodeId is a known satellite node. */
+  isSatelliteNode(nodeId: string): boolean {
+    const ctx = this.satelliteContexts.get(nodeId);
+    if (!ctx) return false;
+    // Stale check (10 min)
+    return Date.now() - ctx.ts < 600_000;
+  }
+
+  /** Queue a tool request for a satellite node. Returns a promise that resolves when the satellite responds. */
+  queueToolForSatellite(
+    nodeId: string,
+    id: string,
+    tool: string,
+    params: Record<string, unknown>,
+    timeout?: number,
+  ): Promise<Record<string, unknown>> {
+    // Check if satellite supports this tool
+    const ctx = this.satelliteContexts.get(nodeId);
+    if (ctx?.tools && !ctx.tools.includes(tool)) {
+      return Promise.reject(new Error(`Satellite "${nodeId}" does not support tool "${tool}"`));
+    }
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.removeSatelliteTool(nodeId, id);
+        reject(new Error(`Satellite tool "${tool}" timed out on "${nodeId}"`));
+      }, timeout ?? SATELLITE_TOOL_TIMEOUT);
+
+      const entry: PendingSatelliteTool = { id, tool, params, from: this.config.nodeId, ts: Date.now(), resolve, reject, timer };
+      const queue = this.satelliteToolQueue.get(nodeId) ?? [];
+      queue.push(entry);
+      this.satelliteToolQueue.set(nodeId, queue);
+
+      // Wake up any long-polling satellite client for this node
+      this.flushSatelliteWaiters(nodeId);
+    });
+  }
+
+  private removeSatelliteTool(nodeId: string, id: string) {
+    const queue = this.satelliteToolQueue.get(nodeId);
+    if (!queue) return;
+    const idx = queue.findIndex(t => t.id === id);
+    if (idx >= 0) {
+      clearTimeout(queue[idx].timer);
+      queue.splice(idx, 1);
+    }
+    if (queue.length === 0) this.satelliteToolQueue.delete(nodeId);
+  }
+
+  /** POST /api/satellite/tool/result — satellite posts tool execution result */
+  private async handleSatelliteToolResult(req: IncomingMessage, res: ServerResponse) {
+    try {
+      const body = await readBody(req);
+      const { id, success, result, error } = JSON.parse(body);
+
+      if (!id) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "id required" }));
+        return;
+      }
+
+      // Find and resolve the pending tool request
+      let found = false;
+      for (const [nodeId, queue] of this.satelliteToolQueue) {
+        const idx = queue.findIndex(t => t.id === id);
+        if (idx >= 0) {
+          const pending = queue[idx];
+          clearTimeout(pending.timer);
+          queue.splice(idx, 1);
+          if (queue.length === 0) this.satelliteToolQueue.delete(nodeId);
+
+          if (success && result) {
+            pending.resolve(typeof result === "object" ? result : { result });
+          } else {
+            pending.reject(new Error(error ?? "Satellite tool execution failed"));
+          }
+          found = true;
+          break;
+        }
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: found }));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  // ── Event ingestion (Shortcuts automations, etc.) ──────────────
+
+  /** POST /api/events/ingest — receive events from external sources (e.g. Apple Shortcuts) */
+  private async handleEventIngest(req: IncomingMessage, res: ServerResponse) {
+    try {
+      const body = await readBody(req);
+      const raw = JSON.parse(body);
+
+      // Support single event or batch
+      const items: Array<Record<string, unknown>> = Array.isArray(raw) ? raw : [raw];
+      const ingested: IngestedEvent[] = [];
+
+      for (const item of items) {
+        if (!item.type) continue;
+        const event: IngestedEvent = {
+          id: crypto.randomUUID(),
+          source: String(item.source || "unknown"),
+          type: String(item.type),
+          data: (typeof item.data === "object" && item.data !== null ? item.data : { value: item.data ?? item }) as Record<string, unknown>,
+          ts: typeof item.ts === "number" ? Math.min(item.ts, Date.now()) : Date.now(),
+          consumed: false,
+        };
+        this.ingestedEvents.push(event);
+        ingested.push(event);
+      }
+
+      // Trim ring buffer
+      if (this.ingestedEvents.length > MAX_INGESTED_EVENTS) {
+        this.ingestedEvents.splice(0, this.ingestedEvents.length - MAX_INGESTED_EVENTS);
+      }
+
+      // Also push as satellite event so polling clients get notified
+      for (const event of ingested) {
+        this.pushSatelliteEvent({
+          ts: event.ts,
+          type: "event_ingested" as SatelliteEvent["type"],
+          data: { id: event.id, source: event.source, type: event.type },
+        });
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, count: ingested.length, ids: ingested.map(e => e.id) }));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  /** GET /api/events?type=<type>&source=<source>&since=<ts>&unconsumed=true&limit=<n> */
+  private handleEventQuery(req: IncomingMessage, res: ServerResponse) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const type = url.searchParams.get("type") || undefined;
+    const source = url.searchParams.get("source") || undefined;
+    const since = parseInt(url.searchParams.get("since") ?? "0", 10) || 0;
+    const unconsumed = url.searchParams.get("unconsumed") === "true";
+    const limit = Math.min(parseInt(url.searchParams.get("limit") ?? "50", 10) || 50, 200);
+
+    this.evictStaleEvents();
+
+    let events = this.ingestedEvents;
+    if (since > 0) events = events.filter(e => e.ts > since);
+    if (type) events = events.filter(e => e.type === type);
+    if (source) events = events.filter(e => e.source === source);
+    if (unconsumed) events = events.filter(e => !e.consumed);
+
+    // Return newest first, limited
+    const result = events.slice(-limit).reverse();
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ events: result, total: events.length }));
+  }
+
+  /** POST /api/events/consume — mark events as consumed by id(s) */
+  private async handleEventConsume(req: IncomingMessage, res: ServerResponse) {
+    try {
+      const body = await readBody(req);
+      const { ids } = JSON.parse(body);
+      if (!Array.isArray(ids)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "ids array required" }));
+        return;
+      }
+
+      const idSet = new Set<string>(ids);
+      let consumed = 0;
+      for (const event of this.ingestedEvents) {
+        if (idSet.has(event.id) && !event.consumed) {
+          event.consumed = true;
+          consumed++;
+        }
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, consumed }));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid request" }));
+    }
+  }
+
+  /** Evict events older than TTL. Centralizes stale-event cleanup. */
+  private evictStaleEvents() {
+    const cutoff = Date.now() - INGESTED_EVENT_TTL;
+    const firstValid = this.ingestedEvents.findIndex(e => e.ts > cutoff);
+    if (firstValid > 0) {
+      this.ingestedEvents.splice(0, firstValid);
+    } else if (firstValid === -1 && this.ingestedEvents.length > 0) {
+      this.ingestedEvents.length = 0;
+    }
+  }
+
+  /** Get unconsumed events (for agent context injection). */
+  getUnconsumedEvents(limit = 10): IngestedEvent[] {
+    this.evictStaleEvents();
+    return this.ingestedEvents.filter(e => !e.consumed).slice(-limit);
+  }
+
+  /** Get all ingested events (for tool queries). */
+  queryEvents(opts?: { type?: string; source?: string; since?: number; unconsumed?: boolean; limit?: number }): IngestedEvent[] {
+    this.evictStaleEvents();
+
+    let events = this.ingestedEvents;
+    if (opts?.since) events = events.filter(e => e.ts > opts.since!);
+    if (opts?.type) events = events.filter(e => e.type === opts.type);
+    if (opts?.source) events = events.filter(e => e.source === opts.source);
+    if (opts?.unconsumed) events = events.filter(e => !e.consumed);
+    return events.slice(-(opts?.limit ?? 50)).reverse();
+  }
+
+  /** Mark events as consumed by id(s). */
+  consumeEvents(ids: string[]): number {
+    const idSet = new Set(ids);
+    let consumed = 0;
+    for (const event of this.ingestedEvents) {
+      if (idSet.has(event.id) && !event.consumed) {
+        event.consumed = true;
+        consumed++;
+      }
+    }
+    return consumed;
+  }
+
+  /** Get all satellite contexts (for use by other components). */
+  getSatelliteContexts(): SatelliteContext[] {
+    // Filter out stale contexts (> 10 minutes)
+    const now = Date.now();
+    const result: SatelliteContext[] = [];
+    for (const [nodeId, ctx] of this.satelliteContexts) {
+      if (now - ctx.ts < 600_000) {
+        result.push(ctx);
+      } else {
+        this.satelliteContexts.delete(nodeId);
+      }
+    }
+    return result;
+  }
 }
+