mulmoclaude 0.1.0

package/server/events/relay-client.ts

@@ -0,0 +1,288 @@
+// MulmoBridge Relay WebSocket client.
+//
+// Connects to the Relay (Cloudflare Workers) and forwards incoming
+// platform messages to the chat-service relay function. Handles
+// reconnection with exponential backoff.
+//
+// NOTE: packages/relay/src/client.ts is a parallel implementation
+// for browser/edge environments using the global WebSocket API.
+// This module uses the `ws` npm package for Node.js. If you change
+// reconnection logic or URL handling here, check the other file too.
+
+import WebSocket from "ws";
+import type { ChatService } from "@mulmobridge/chat-service";
+import { ONE_SECOND_MS } from "../utils/time.js";
+
+type RelayFn = ChatService["relay"];
+
+// ── Types ────────────────────────────────────────────────────
+
+interface RelayMessage {
+  id: string;
+  platform: string;
+  senderId: string;
+  chatId: string;
+  text: string;
+  receivedAt: string;
+  replyToken?: string;
+}
+
+interface RelayResponse {
+  platform: string;
+  chatId: string;
+  text: string;
+  replyToken?: string;
+}
+
+interface Logger {
+  info(prefix: string, msg: string, data?: unknown): void;
+  warn(prefix: string, msg: string, data?: unknown): void;
+  error(prefix: string, msg: string, data?: unknown): void;
+}
+
+export interface RelayClientDeps {
+  relayUrl: string;
+  relayToken: string;
+  relay: RelayFn;
+  logger: Logger;
+}
+
+export interface RelayClientHandle {
+  disconnect(): void;
+}
+
+// ── Constants ────────────────────────────────────────────────
+
+const LOG_PREFIX = "relay-client";
+const TRANSPORT_ID = "relay";
+const MIN_RECONNECT_MS = ONE_SECOND_MS;
+const MAX_RECONNECT_MS = 30 * ONE_SECOND_MS;
+const MAX_RESPONSE_QUEUE = 100;
+
+// Close codes that indicate a permanent/terminal error — no point
+// reconnecting until the configuration is fixed.
+const TERMINAL_CLOSE_CODES = new Set([
+  1008, // Policy violation (e.g. auth rejected)
+  4401, // Custom: unauthorized
+  4403, // Custom: forbidden
+]);
+
+// ── Helpers ─────────────────────────────────────────────────
+
+function isRelayMessage(value: unknown): value is RelayMessage {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.id === "string" &&
+    typeof obj.platform === "string" &&
+    typeof obj.chatId === "string" &&
+    typeof obj.text === "string" &&
+    obj.text !== "" &&
+    obj.chatId !== ""
+  );
+}
+
+// ── Factory ─────────────────────────────────────────────────
+
+export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
+  const { relayUrl, relayToken, relay, logger } = deps;
+
+  let ws: WebSocket | null = null;
+  let reconnectMs = MIN_RECONNECT_MS;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  const responseQueue: RelayResponse[] = [];
+
+  function buildUrl(): string {
+    const url = new URL(relayUrl);
+    url.searchParams.set("token", relayToken);
+    return url.toString();
+  }
+
+  function connect(): void {
+    if (stopped) return;
+
+    try {
+      ws = new WebSocket(buildUrl());
+    } catch (err) {
+      logger.error(LOG_PREFIX, "failed to create WebSocket", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      scheduleReconnect();
+      return;
+    }
+
+    ws.on("open", () => {
+      logger.info(LOG_PREFIX, "connected", { url: relayUrl });
+      reconnectMs = MIN_RECONNECT_MS;
+      flushResponseQueue();
+    });
+
+    ws.on("message", (data) => {
+      handleMessage(String(data));
+    });
+
+    ws.on("close", (code, reason) => {
+      ws = null;
+      if (TERMINAL_CLOSE_CODES.has(code)) {
+        logger.error(LOG_PREFIX, "terminal close, not reconnecting", {
+          code,
+          reason: String(reason),
+        });
+        return;
+      }
+      logger.info(LOG_PREFIX, "disconnected", {
+        code,
+        reason: String(reason),
+      });
+      scheduleReconnect();
+    });
+
+    ws.on("error", (err) => {
+      logger.warn(LOG_PREFIX, "connection error", {
+        error: err.message,
+      });
+      // close event will follow, triggering reconnect
+    });
+  }
+
+  function scheduleReconnect(): void {
+    if (stopped) return;
+    logger.info(LOG_PREFIX, "reconnecting", { delayMs: reconnectMs });
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, reconnectMs);
+    reconnectMs = Math.min(reconnectMs * 2, MAX_RECONNECT_MS);
+  }
+
+  async function handleMessage(raw: string): Promise<void> {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      logger.warn(LOG_PREFIX, "invalid JSON from relay", {
+        length: raw.length,
+      });
+      return;
+    }
+
+    if (!isRelayMessage(parsed)) {
+      logger.warn(LOG_PREFIX, "malformed relay message");
+      return;
+    }
+    const msg = parsed;
+
+    logger.info(LOG_PREFIX, "message received", {
+      id: msg.id,
+      platform: msg.platform,
+      chatId: msg.chatId,
+      textLength: msg.text.length,
+    });
+
+    // Double-underscore separator avoids collisions — platform names
+    // are from a fixed set (PLATFORMS constant) and none contain "__".
+    // Single "-" is unsafe because "google-chat" + "X" collides with
+    // "google" + "chat-X".
+    const externalChatId = `${msg.platform}__${msg.chatId}`;
+
+    try {
+      const result = await relay({
+        transportId: TRANSPORT_ID,
+        externalChatId,
+        text: msg.text,
+      });
+
+      const replyText = result.kind === "ok" ? result.reply : `Error: ${result.message}`;
+
+      sendResponse({
+        platform: msg.platform,
+        chatId: msg.chatId,
+        text: replyText,
+        replyToken: msg.replyToken,
+      });
+    } catch (err) {
+      logger.error(LOG_PREFIX, "relay processing failed", {
+        id: msg.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      sendResponse({
+        platform: msg.platform,
+        chatId: msg.chatId,
+        text: "Error: failed to process message",
+        replyToken: msg.replyToken,
+      });
+    }
+  }
+
+  function enqueueResponse(response: RelayResponse): void {
+    if (responseQueue.length >= MAX_RESPONSE_QUEUE) {
+      logger.error(LOG_PREFIX, "response queue full, dropping oldest", {
+        platform: response.platform,
+        chatId: response.chatId,
+      });
+      responseQueue.shift();
+    }
+    responseQueue.push(response);
+  }
+
+  function trySend(response: RelayResponse): boolean {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+    try {
+      ws.send(JSON.stringify(response), (err) => {
+        if (err && !stopped) {
+          logger.warn(LOG_PREFIX, "send failed, requeueing", {
+            platform: response.platform,
+            chatId: response.chatId,
+            error: err.message,
+          });
+          enqueueResponse(response);
+        }
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function sendResponse(response: RelayResponse): void {
+    if (trySend(response)) return;
+    enqueueResponse(response);
+    logger.error(LOG_PREFIX, "response queued (not connected)", {
+      platform: response.platform,
+      chatId: response.chatId,
+      queueSize: responseQueue.length,
+    });
+  }
+
+  function flushResponseQueue(): void {
+    if (responseQueue.length === 0) return;
+    logger.info(LOG_PREFIX, "flushing response queue", {
+      count: responseQueue.length,
+    });
+    while (responseQueue.length > 0) {
+      if (!ws || ws.readyState !== WebSocket.OPEN) break;
+      const response = responseQueue[0]!;
+      if (!trySend(response)) break;
+      responseQueue.shift();
+    }
+  }
+
+  function disconnect(): void {
+    stopped = true;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (ws) {
+      ws.close(1000, "shutdown");
+      ws = null;
+    }
+    logger.info(LOG_PREFIX, "stopped");
+  }
+
+  // Start immediately
+  connect();
+
+  return { disconnect };
+}

package/server/events/scheduler-adapter.ts

@@ -0,0 +1,302 @@
+// Adapter that wires the pure scheduler library (server/utils/scheduler/)
+// to the MulmoClaude runtime. Registers system tasks, runs catch-up on
+// startup, and persists execution state + logs.
+//
+// Deliberately thin — all complex logic lives in the scheduler library.
+// This file's job is I/O binding and MulmoClaude-specific plumbing.
+
+import { existsSync } from "fs";
+import { readFile, appendFile, mkdir } from "fs/promises";
+import path from "path";
+import { workspacePath } from "../workspace/workspace.js";
+import { writeFileAtomic } from "../utils/files/atomic.js";
+import { log } from "../system/logger/index.js";
+import { errorMessage } from "../utils/errors.js";
+import { ONE_SECOND_MS } from "../utils/time.js";
+import type { ITaskManager, TaskDefinition } from "./task-manager/index.js";
+import {
+  type TaskSchedule,
+  type TaskExecutionState,
+  type TaskLogEntry,
+  type CatchUpTask,
+  type TaskTrigger,
+  emptyState,
+  computeCatchUpPlan,
+  nextWindowAfter,
+  loadState,
+  updateAndSave,
+  appendLogEntry,
+  queryLog,
+  SCHEDULE_TYPES,
+  TASK_RESULTS,
+  TASK_TRIGGERS,
+  MISSED_RUN_POLICIES,
+  type StateMap,
+  type StateDeps,
+  type LogDeps,
+} from "@receptron/task-scheduler";
+
+// ── Paths ────────────────────────────────────────────────────────
+
+const SCHEDULER_CONFIG_DIR = "config/scheduler";
+const SCHEDULER_DATA_DIR = "data/scheduler/logs";
+
+function stateFilePath(root = workspacePath): string {
+  return path.join(root, SCHEDULER_CONFIG_DIR, "state.json");
+}
+
+function logsDir(root = workspacePath): string {
+  return path.join(root, SCHEDULER_DATA_DIR);
+}
+
+// ── I/O deps (real filesystem) ───────────────────────────────────
+
+const stateDeps: StateDeps = {
+  readFile: (p: string) => readFile(p, "utf-8"),
+  writeFileAtomic: (p: string, content: string) => writeFileAtomic(p, content),
+  exists: existsSync,
+};
+
+const logDeps: LogDeps = {
+  appendFile: (p: string, content: string) => appendFile(p, content),
+  readFile: (p: string) => readFile(p, "utf-8"),
+  exists: existsSync,
+  ensureDir: (p: string) => mkdir(p, { recursive: true }).then(() => {}),
+};
+
+// ── System task registry ─────────────────────────────────────────
+
+export interface SystemTaskDef {
+  id: string;
+  name: string;
+  description: string;
+  schedule: TaskDefinition["schedule"];
+  missedRunPolicy: typeof MISSED_RUN_POLICIES.skip | typeof MISSED_RUN_POLICIES.runOnce | typeof MISSED_RUN_POLICIES.runAll;
+  run: () => Promise<void>;
+}
+
+// ── Public API ───────────────────────────────────────────────────
+
+let stateMap: StateMap = new Map();
+const systemTasks: SystemTaskDef[] = [];
+let taskManagerRef: ITaskManager | null = null;
+
+/**
+ * Initialize the scheduler adapter. Call once at server startup
+ * AFTER the task-manager is created but BEFORE `taskManager.start()`.
+ */
+export async function initScheduler(taskManager: ITaskManager, tasks: SystemTaskDef[]): Promise<void> {
+  await mkdir(path.dirname(stateFilePath()), { recursive: true });
+  await mkdir(logsDir(), { recursive: true });
+
+  stateMap = await loadState(stateFilePath(), stateDeps);
+  systemTasks.length = 0;
+  systemTasks.push(...tasks);
+  taskManagerRef = taskManager;
+
+  // Run catch-up
+  const catchUpTasks: CatchUpTask[] = tasks.map((t) => ({
+    id: t.id,
+    name: t.name,
+    schedule: toCoreSchedule(t.schedule),
+    missedRunPolicy: t.missedRunPolicy,
+    enabled: true,
+  }));
+  const plan = computeCatchUpPlan(catchUpTasks, stateMap, Date.now());
+
+  for (const skip of plan.skipped) {
+    log.info("scheduler", "catch-up skipped", {
+      taskId: skip.taskId,
+      windows: skip.windowCount,
+    });
+    await safeUpdateState(skip.taskId, { lastRunAt: skip.lastWindow });
+  }
+
+  if (plan.runs.length > 0) {
+    log.info("scheduler", "catch-up enqueued", {
+      runs: plan.runs.length,
+    });
+    for (const run of plan.runs) {
+      const task = tasks.find((t) => t.id === run.taskId);
+      if (!task) continue;
+      await executeAndLog(task, run.context.scheduledFor, TASK_TRIGGERS.catchUp);
+    }
+  }
+
+  // Register with task-manager for ongoing ticks
+  for (const task of tasks) {
+    taskManager.registerTask({
+      id: task.id,
+      description: task.description,
+      schedule: task.schedule,
+      run: async () => {
+        const windowIso = computeCurrentWindow(task);
+        await executeAndLog(task, windowIso, TASK_TRIGGERS.scheduled);
+      },
+    });
+  }
+
+  log.info("scheduler", "initialized", {
+    tasks: tasks.map((t) => t.id),
+    stateEntries: stateMap.size,
+  });
+}
+
+/** Apply a schedule override to a running system task.
+ *  Updates the in-memory task definition, the task-manager, and
+ *  recalculates nextScheduledAt in persisted state. */
+export async function applyScheduleOverride(taskId: string, schedule: SystemTaskDef["schedule"]): Promise<boolean> {
+  const task = systemTasks.find((t) => t.id === taskId);
+  if (!task || !taskManagerRef) return false;
+  if (!taskManagerRef.updateSchedule(taskId, schedule)) return false;
+  task.schedule = schedule;
+
+  // Recalculate next window so the UI reflects the new schedule
+  const nextScheduledAt = computeNextScheduled(task);
+  await safeUpdateState(taskId, { nextScheduledAt });
+
+  return true;
+}
+
+/** Query execution logs — used by API routes. */
+export async function getSchedulerLogs(opts: { since?: string; taskId?: string; limit?: number }): Promise<TaskLogEntry[]> {
+  return queryLog(logsDir(), opts, logDeps);
+}
+
+/** Get all task states — used by API routes. */
+export function getSchedulerTasks(): Array<{
+  id: string;
+  name: string;
+  description: string;
+  schedule: TaskDefinition["schedule"];
+  missedRunPolicy: string;
+  state: TaskExecutionState;
+}> {
+  return systemTasks.map((t) => ({
+    id: t.id,
+    name: t.name,
+    description: t.description,
+    schedule: t.schedule,
+    missedRunPolicy: t.missedRunPolicy,
+    state: stateMap.get(t.id) ?? emptyState(t.id),
+  }));
+}
+
+// ── Internal ─────────────────────────────────────────────────────
+
+async function executeAndLog(task: SystemTaskDef, scheduledFor: string, trigger: TaskTrigger): Promise<void> {
+  const startedAt = new Date().toISOString();
+  const startMs = Date.now();
+  let errMsg: string | null = null;
+  try {
+    await task.run();
+  } catch (err) {
+    errMsg = errorMessage(err);
+    log.error("scheduler", "task failed", {
+      taskId: task.id,
+      error: errMsg,
+    });
+  }
+  const durationMs = Date.now() - startMs;
+  // Persistence is best-effort — never let disk failures propagate
+  // to the tick loop or abort startup catch-up.
+  await safePersist(task, scheduledFor, startedAt, durationMs, trigger, errMsg);
+}
+
+/** Best-effort persistence — state and log are independent. A failure
+ *  in one does not block the other, and neither propagates upward. */
+async function safePersist(
+  task: SystemTaskDef,
+  scheduledFor: string,
+  startedAt: string,
+  durationMs: number,
+  trigger: TaskTrigger,
+  errMsg: string | null,
+): Promise<void> {
+  const isSuccess = errMsg === null;
+  const currentState = stateMap.get(task.id);
+  try {
+    await updateAndSave(
+      stateFilePath(),
+      stateMap,
+      task.id,
+      {
+        lastRunAt: scheduledFor,
+        lastRunResult: isSuccess ? TASK_RESULTS.success : TASK_RESULTS.error,
+        lastRunDurationMs: durationMs,
+        lastErrorMessage: errMsg,
+        consecutiveFailures: isSuccess ? 0 : (currentState?.consecutiveFailures ?? 0) + 1,
+        totalRuns: (currentState?.totalRuns ?? 0) + 1,
+        nextScheduledAt: computeNextScheduled(task),
+      },
+      stateDeps,
+    );
+  } catch (err) {
+    log.warn("scheduler", "state persistence failed", {
+      taskId: task.id,
+      error: String(err),
+    });
+  }
+  try {
+    await appendLogEntry(
+      logsDir(),
+      {
+        taskId: task.id,
+        taskName: task.name,
+        scheduledFor,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        result: isSuccess ? TASK_RESULTS.success : TASK_RESULTS.error,
+        durationMs,
+        trigger,
+        ...(errMsg !== null && { errorMessage: errMsg }),
+      },
+      logDeps,
+    );
+  } catch (err) {
+    log.warn("scheduler", "log persistence failed", {
+      taskId: task.id,
+      error: String(err),
+    });
+  }
+}
+
+/** Safe state update — swallows errors. */
+async function safeUpdateState(taskId: string, patch: Partial<TaskExecutionState>): Promise<void> {
+  try {
+    await updateAndSave(stateFilePath(), stateMap, taskId, patch, stateDeps);
+  } catch (err) {
+    log.warn("scheduler", "state update failed", {
+      taskId,
+      error: String(err),
+    });
+  }
+}
+
+/** Compute the window boundary that the current tick belongs to.
+ *  For scheduled runs, this is the epoch-aligned window — not the
+ *  wall-clock time of execution. This keeps lastRunAt consistent
+ *  with catch-up's window-based accounting. */
+function computeCurrentWindow(task: SystemTaskDef): string {
+  const coreSchedule = toCoreSchedule(task.schedule);
+  // The window that just fired is the latest one at or before now.
+  const nowMs = Date.now();
+  const windowMs = nextWindowAfter(coreSchedule, nowMs - (coreSchedule.type === SCHEDULE_TYPES.interval ? coreSchedule.intervalSec * ONE_SECOND_MS : 0));
+  return windowMs !== null && windowMs <= nowMs ? new Date(windowMs).toISOString() : new Date(nowMs).toISOString();
+}
+
+function computeNextScheduled(task: SystemTaskDef): string | null {
+  const coreSchedule = toCoreSchedule(task.schedule);
+  const next = nextWindowAfter(coreSchedule, Date.now() + 1);
+  return next !== null ? new Date(next).toISOString() : null;
+}
+
+function toCoreSchedule(schedule: TaskDefinition["schedule"]): TaskSchedule {
+  if (schedule.type === SCHEDULE_TYPES.interval) {
+    return {
+      type: SCHEDULE_TYPES.interval,
+      intervalSec: Math.round(schedule.intervalMs / ONE_SECOND_MS),
+    };
+  }
+  return schedule;
+}