mulmoclaude 0.1.0

package/server/events/session-store/index.ts

@@ -0,0 +1,492 @@
+// Server-side session state store. Replaces the lightweight
+// `server/sessions.ts` SSE-send registry with a pub/sub-backed
+// store that holds authoritative state per chat session. Multiple
+// clients can subscribe to the same session channel and receive
+// identical events.
+
+import { appendFile } from "fs/promises";
+import type { IPubSub } from "../pub-sub/index.js";
+import { PUBSUB_CHANNELS, sessionChannel } from "../../../src/config/pubsubChannels.js";
+import { log } from "../../system/logger/index.js";
+import { updateHasUnread } from "../../utils/files/session-io.js";
+import { EVENT_TYPES, GENERATION_KINDS, type GenerationKind, type PendingGeneration, generationKey } from "../../../src/types/events.js";
+import { ONE_HOUR_MS, ONE_MINUTE_MS } from "../../utils/time.js";
+
+// ── Types ──────────────────────────────────────────────────────
+
+export interface ToolCallHistoryItem {
+  toolUseId: string;
+  toolName: string;
+  args: unknown;
+  timestamp: number;
+  result?: string;
+  error?: string;
+}
+
+export interface ServerSession {
+  chatSessionId: string;
+  roleId: string;
+  isRunning: boolean;
+  hasUnread: boolean;
+  statusMessage: string;
+  toolCallHistory: ToolCallHistoryItem[];
+  resultsFilePath: string;
+  selectedImageData?: string;
+  startedAt: string;
+  updatedAt: string;
+  /** Kills the spawned Claude CLI process for this session. */
+  abortRun?: () => void;
+  /**
+   * In-flight background generations keyed by `generationKey(kind, filePath, key)`.
+   * The value carries the decomposed (kind, filePath, key) so consumers never
+   * have to parse the opaque composite key back out. Non-empty means the
+   * session has ongoing work even when `isRunning` (agent turn) is false —
+   * used to keep the busy indicator lit across view navigation.
+   */
+  pendingGenerations: Record<string, PendingGeneration>;
+}
+
+// ── Constants ──────────────────────────────────────────────────
+
+const IDLE_EVICTION_MS = ONE_HOUR_MS;
+const EVICTION_CHECK_INTERVAL_MS = 5 * ONE_MINUTE_MS;
+
+// ── Store ──────────────────────────────────────────────────────
+
+const store = new Map<string, ServerSession>();
+/**
+ * Parallel pending-generation tracking for sessions that aren't in the
+ * in-memory store. The MulmoScript view can be opened on a session
+ * whose full ServerSession entry never existed or was evicted after
+ * idle timeout — we still want to mark unread and fire
+ * notifySessionsChanged when the work drains. Cleared on drain.
+ */
+const storelessPending = new Map<string, Set<string>>();
+let pubsub: IPubSub | null = null;
+let evictionTimer: ReturnType<typeof setInterval> | null = null;
+
+export function initSessionStore(ps: IPubSub): void {
+  pubsub = ps;
+  if (evictionTimer) clearInterval(evictionTimer);
+  evictionTimer = setInterval(evictIdleSessions, EVICTION_CHECK_INTERVAL_MS);
+}
+
+// ── Session lifecycle ──────────────────────────────────────────
+
+export function getSession(chatSessionId: string): ServerSession | undefined {
+  return store.get(chatSessionId);
+}
+
+export function getOrCreateSession(
+  chatSessionId: string,
+  opts: {
+    roleId: string;
+    resultsFilePath: string;
+    selectedImageData?: string;
+    startedAt: string;
+    updatedAt: string;
+    hasUnread?: boolean;
+  },
+): ServerSession {
+  const existing = store.get(chatSessionId);
+  if (existing) {
+    existing.selectedImageData = opts.selectedImageData;
+    existing.updatedAt = opts.updatedAt;
+    return existing;
+  }
+  const session: ServerSession = {
+    chatSessionId,
+    roleId: opts.roleId,
+    isRunning: false,
+    hasUnread: opts.hasUnread ?? false,
+    statusMessage: "",
+    toolCallHistory: [],
+    resultsFilePath: opts.resultsFilePath,
+    selectedImageData: opts.selectedImageData,
+    startedAt: opts.startedAt,
+    updatedAt: opts.updatedAt,
+    pendingGenerations: {},
+  };
+  store.set(chatSessionId, session);
+  return session;
+}
+
+function removeSession(chatSessionId: string): void {
+  store.delete(chatSessionId);
+  notifySessionsChanged();
+}
+
+// ── State mutations (publish to pub/sub) ───────────────────────
+
+/** Mark a session as running. Rejects if already running (409). */
+export function beginRun(chatSessionId: string, abortRun: () => void): boolean {
+  const session = store.get(chatSessionId);
+  if (!session) return false;
+  if (session.isRunning) return false;
+  session.isRunning = true;
+  session.statusMessage = "";
+  session.toolCallHistory = [];
+  session.abortRun = abortRun;
+  session.updatedAt = new Date().toISOString();
+  notifySessionsChanged();
+  return true;
+}
+
+/** Mark a session as finished. Sets hasUnread = true. */
+export function endRun(chatSessionId: string): void {
+  const session = store.get(chatSessionId);
+  if (!session) return;
+  session.isRunning = false;
+  session.hasUnread = true;
+  session.statusMessage = "";
+  session.abortRun = undefined;
+  session.updatedAt = new Date().toISOString();
+  persistHasUnread(chatSessionId, true);
+  publishToSessionChannel(chatSessionId, {
+    type: EVENT_TYPES.sessionFinished,
+  });
+  notifySessionsChanged();
+}
+
+/** Cancel a running session by killing the child process. */
+export function cancelRun(chatSessionId: string): boolean {
+  const session = store.get(chatSessionId);
+  if (!session?.isRunning || !session.abortRun) return false;
+  session.abortRun();
+  return true;
+}
+
+/** Clear the unread flag (called when a client views the session).
+ *  Awaits the disk write so the caller can respond only after the
+ *  flag is actually persisted — avoids the race where the client
+ *  refetches before the write lands and sees the stale value. */
+export async function markRead(chatSessionId: string): Promise<void> {
+  const session = store.get(chatSessionId);
+  if (!session) {
+    // No in-memory session — still persist to disk so the flag is
+    // cleared for the next server restart / session listing.
+    await persistHasUnread(chatSessionId, false);
+    return;
+  }
+  if (!session.hasUnread) return;
+  session.hasUnread = false;
+  await persistHasUnread(chatSessionId, false);
+  notifySessionsChanged();
+}
+
+// ── Event publishing ───────────────────────────────────────────
+
+/** Publish an agent event to the session's channel + update store. */
+export function pushSessionEvent(chatSessionId: string, event: Record<string, unknown>): void {
+  const type = event.type as string;
+  const isGenerationEvent = type === EVENT_TYPES.generationStarted || type === EVENT_TYPES.generationFinished;
+
+  // Non-generation events keep the pre-existing "store or drop"
+  // behavior: toolCall / toolCallResult / status fire only during a
+  // live agent turn (which always has a store entry), and
+  // rolesUpdated / sessionFinished are equally tied to in-store
+  // sessions. Publishing them for evicted sessions would broaden the
+  // wire contract without a concrete need.
+  //
+  // Generation events are the exception — a plugin view (e.g.
+  // MulmoScript) can kick off work on a session whose store entry
+  // never existed or was evicted after idle timeout, and the client
+  // subscription lives on the channel, not on any server-side
+  // session object. We always deliver those so the UI can update.
+  const session = store.get(chatSessionId);
+  if (!session && !isGenerationEvent) return;
+  publishToSessionChannel(chatSessionId, event);
+
+  const generationDelta = resolveGenerationDelta(chatSessionId, type, event);
+  if (generationDelta === "same") return;
+  if (generationDelta === "started") {
+    notifySessionsChanged();
+    return;
+  }
+
+  // Drained: flag hasUnread, same semantics as endRun(). Clients
+  // viewing the session clear it via markRead.
+  if (session) {
+    session.hasUnread = true;
+    // Store is the source of truth, so the refetch already sees the
+    // flag via `live.hasUnread` — the disk write is just a backstop
+    // across server restarts and can stay fire-and-forget.
+    persistHasUnread(chatSessionId, true).catch(() => {});
+    notifySessionsChanged();
+    return;
+  }
+
+  // Storeless: meta.hasUnread on disk is the ONLY place the flag lives.
+  // If we notified before the write completed, the client's refetch
+  // would read the stale pre-drain value. Sequence: persist, then
+  // notify.
+  persistHasUnread(chatSessionId, true)
+    .catch(() => {})
+    .then(() => notifySessionsChanged());
+}
+
+/**
+ * Dispatch the event to whichever pending tracker the session has.
+ * Returns the empty↔non-empty transition so the caller can decide
+ * whether to flip hasUnread and notify.
+ */
+function resolveGenerationDelta(chatSessionId: string, type: string, event: Record<string, unknown>): GenerationDelta {
+  const session = store.get(chatSessionId);
+  if (session) return applyEventToSession(session, type, event);
+  if (type === EVENT_TYPES.generationStarted || type === EVENT_TYPES.generationFinished) {
+    return updateStorelessPending(chatSessionId, type, event);
+  }
+  return "same";
+}
+
+function updateStorelessPending(chatSessionId: string, type: string, event: Record<string, unknown>): GenerationDelta {
+  const payload = parseGenerationPayload(event);
+  if (!payload) {
+    log.warn("session-store", "malformed generation event", {
+      chatSessionId,
+      type,
+    });
+    return "same";
+  }
+  const mapKey = generationKey(payload.kind, payload.filePath, payload.key);
+  const existing = storelessPending.get(chatSessionId);
+  const wasEmpty = !existing || existing.size === 0;
+
+  if (type === EVENT_TYPES.generationStarted) {
+    const set = existing ?? new Set<string>();
+    set.add(mapKey);
+    if (!existing) storelessPending.set(chatSessionId, set);
+  } else if (existing) {
+    existing.delete(mapKey);
+    if (existing.size === 0) storelessPending.delete(chatSessionId);
+  }
+
+  const isEmpty = (storelessPending.get(chatSessionId)?.size ?? 0) === 0;
+  if (wasEmpty === isEmpty) return "same";
+  return isEmpty ? "drained" : "started";
+}
+
+/**
+ * How a generation event affected the session's pendingGenerations set:
+ *
+ * - `started`: empty → non-empty (first generation in a quiet session)
+ * - `drained`: non-empty → empty (last pending generation finished)
+ * - `same`: no transition (parallel starts/finishes within a burst,
+ *   or a non-generation event type)
+ *
+ * Callers use this to decide whether to fire `notifySessionsChanged()`
+ * and whether to flip hasUnread on drain.
+ */
+type GenerationDelta = "started" | "drained" | "same";
+
+/** Fields pulled off a validated generation event. */
+interface GenerationPayload {
+  kind: GenerationKind;
+  filePath: string;
+  key: string;
+}
+
+const GENERATION_KIND_VALUES: ReadonlySet<string> = new Set(Object.values(GENERATION_KINDS));
+
+function isGenerationKind(v: unknown): v is GenerationKind {
+  return typeof v === "string" && GENERATION_KIND_VALUES.has(v);
+}
+
+/**
+ * Narrow an event's generation fields at runtime. The event arrives
+ * as `Record<string, unknown>` so we can't trust its shape — validate
+ * every field before handing back a typed struct. Unknown kinds or
+ * missing fields return null; the caller should log + no-op.
+ */
+function parseGenerationPayload(event: Record<string, unknown>): GenerationPayload | null {
+  const { kind, filePath, key } = event;
+  if (!isGenerationKind(kind)) return null;
+  if (typeof filePath !== "string" || typeof key !== "string") return null;
+  return { kind, filePath, key };
+}
+
+function applyEventToSession(session: ServerSession, type: string, event: Record<string, unknown>): GenerationDelta {
+  if (type === EVENT_TYPES.toolCall) {
+    session.toolCallHistory.push({
+      toolUseId: event.toolUseId as string,
+      toolName: event.toolName as string,
+      args: event.args,
+      timestamp: Date.now(),
+    });
+  } else if (type === EVENT_TYPES.toolCallResult) {
+    const entry = session.toolCallHistory.find((e) => e.toolUseId === event.toolUseId);
+    if (entry) entry.result = event.content as string;
+  } else if (type === EVENT_TYPES.status) {
+    session.statusMessage = event.message as string;
+    // No notifySessionsChanged() here — status updates are high-frequency
+    // and flow to subscribed clients via the session.<id> channel directly.
+  } else if (type === EVENT_TYPES.generationStarted || type === EVENT_TYPES.generationFinished) {
+    return updatePendingGenerations(session, type, event);
+  }
+  return "same";
+}
+
+function updatePendingGenerations(session: ServerSession, type: string, event: Record<string, unknown>): GenerationDelta {
+  const payload = parseGenerationPayload(event);
+  if (!payload) {
+    log.warn("session-store", "malformed generation event", {
+      chatSessionId: session.chatSessionId,
+      type,
+    });
+    return "same";
+  }
+  const mapKey = generationKey(payload.kind, payload.filePath, payload.key);
+  const wasEmpty = Object.keys(session.pendingGenerations).length === 0;
+
+  if (type === EVENT_TYPES.generationStarted) {
+    session.pendingGenerations[mapKey] = payload;
+  } else {
+    delete session.pendingGenerations[mapKey];
+  }
+
+  const isEmpty = Object.keys(session.pendingGenerations).length === 0;
+  if (wasEmpty === isEmpty) return "same";
+  return isEmpty ? "drained" : "started";
+}
+
+/**
+ * Convenience wrapper for plugin routes that run long async jobs.
+ * Publishes a generationStarted or generationFinished event on the
+ * session channel. Safely no-ops when chatSessionId is missing — lets
+ * callers that aren't inside a session context use the same routes.
+ */
+export function publishGeneration(
+  chatSessionId: string | undefined,
+  kind: GenerationKind,
+  filePath: string,
+  key: string,
+  finished: boolean,
+  error?: string,
+): void {
+  if (!chatSessionId) return;
+  const event: Record<string, unknown> = {
+    type: finished ? EVENT_TYPES.generationFinished : EVENT_TYPES.generationStarted,
+    kind,
+    filePath,
+    key,
+  };
+  if (error) event.error = error;
+  pushSessionEvent(chatSessionId, event);
+}
+
+export type PushToolResultOutcome = { kind: "skipped"; reason: string } | { kind: "processed" };
+
+/** Persist a tool_result to JSONL, then publish to the session channel. */
+export async function pushToolResult(chatSessionId: string, result: unknown): Promise<PushToolResultOutcome> {
+  const session = store.get(chatSessionId);
+  if (!session) return { kind: "skipped", reason: "unknown session" };
+
+  await appendFile(
+    session.resultsFilePath,
+    JSON.stringify({
+      source: "tool",
+      type: EVENT_TYPES.toolResult,
+      result,
+    }) + "\n",
+  );
+  publishToSessionChannel(chatSessionId, {
+    type: EVENT_TYPES.toolResult,
+    result,
+  });
+  return { kind: "processed" };
+}
+
+// ── Query helpers ──────────────────────────────────────────────
+
+export function getSessionImageData(chatSessionId: string): string | undefined {
+  return store.get(chatSessionId)?.selectedImageData;
+}
+
+export function getActiveSessionIds(): Set<string> {
+  const ids = new Set<string>();
+  for (const [id, session] of store) {
+    if (session.isRunning) ids.add(id);
+  }
+  return ids;
+}
+
+// ── In-process session event listeners ────────────────────────
+
+type SessionEventListener = (event: Record<string, unknown>) => void;
+const sessionListeners = new Map<string, Set<SessionEventListener>>();
+
+/**
+ * Subscribe to session events in-process (no WebSocket needed).
+ * Returns an unsubscribe function.
+ */
+export function onSessionEvent(chatSessionId: string, listener: SessionEventListener): () => void {
+  let listeners = sessionListeners.get(chatSessionId);
+  if (!listeners) {
+    listeners = new Set();
+    sessionListeners.set(chatSessionId, listeners);
+  }
+  listeners.add(listener);
+  return () => {
+    listeners!.delete(listener);
+    if (listeners!.size === 0) sessionListeners.delete(chatSessionId);
+  };
+}
+
+// ── Internal helpers ───────────────────────────────────────────
+
+async function persistHasUnread(chatSessionId: string, hasUnread: boolean): Promise<void> {
+  try {
+    await updateHasUnread(chatSessionId, hasUnread);
+  } catch (err) {
+    // updateHasUnread already no-ops when meta is missing (ENOENT is
+    // handled internally). Any error reaching here is unexpected.
+    log.warn("session-store", "persistHasUnread failed", {
+      chatSessionId,
+      hasUnread,
+      error: String(err),
+    });
+  }
+}
+
+function publishToSessionChannel(chatSessionId: string, data: unknown): void {
+  pubsub?.publish(sessionChannel(chatSessionId), data);
+  const listeners = sessionListeners.get(chatSessionId);
+  if (listeners) {
+    for (const listener of listeners) {
+      listener(data as Record<string, unknown>);
+    }
+  }
+}
+
+/** Notify all clients that session state has changed — refetch via REST. */
+function notifySessionsChanged(): void {
+  pubsub?.publish(PUBSUB_CHANNELS.sessions, {});
+}
+
+function evictIdleSessions(): void {
+  const now = Date.now();
+  for (const [id, session] of store) {
+    if (session.isRunning) continue;
+    const age = now - new Date(session.updatedAt).getTime();
+    if (age > IDLE_EVICTION_MS) {
+      log.info("session-store", "evicting idle session", {
+        chatSessionId: id,
+      });
+      removeSession(id);
+    }
+  }
+}
+
+/**
+ * Test-only: clear all in-memory state so a test suite can start
+ * fresh without reloading the module.
+ */
+export function __resetForTests(): void {
+  store.clear();
+  storelessPending.clear();
+  pubsub = null;
+  if (evictionTimer) {
+    clearInterval(evictionTimer);
+    evictionTimer = null;
+  }
+}

package/server/events/task-manager/index.ts

@@ -0,0 +1,181 @@
+import { log } from "../../system/logger/index.js";
+import { ONE_SECOND_MS, ONE_MINUTE_MS, ONE_HOUR_MS } from "../../utils/time.js";
+import { SCHEDULE_TYPES } from "@receptron/task-scheduler";
+
+export type TaskSchedule = { type: typeof SCHEDULE_TYPES.interval; intervalMs: number } | { type: typeof SCHEDULE_TYPES.daily; time: string }; // time: "HH:MM" in UTC
+
+export interface TaskRunContext {
+  taskId: string;
+  now: Date;
+}
+
+export interface TaskDefinition {
+  id: string;
+  description?: string;
+  schedule: TaskSchedule;
+  enabled?: boolean; // default: true
+  /** If set, this task only fires after the named task has completed
+   *  successfully in the current tick cycle. Enforces ordering like
+   *  "news fetch → journal → memory extraction". */
+  dependsOn?: string;
+  run: (ctx: TaskRunContext) => Promise<void>;
+}
+
+export interface ITaskManager {
+  registerTask(def: TaskDefinition): void;
+  removeTask(taskId: string): void;
+  /** Update the schedule of an existing task. Returns false if not found. */
+  updateSchedule(taskId: string, schedule: TaskSchedule): boolean;
+  start(): void;
+  stop(): void;
+  /** Run one tick manually (for testing). */
+  tick(): Promise<void>;
+  listTasks(): Array<{
+    id: string;
+    description?: string;
+    schedule: TaskSchedule;
+    dependsOn?: string;
+  }>;
+}
+
+export interface TaskManagerOptions {
+  tickMs?: number; // default: ONE_MINUTE_MS
+  now?: () => Date; // default: () => new Date()
+}
+
+function isDue(now: Date, schedule: TaskSchedule, tickMs: number): boolean {
+  if (schedule.type === SCHEDULE_TYPES.interval) {
+    const msSinceMidnight = now.getUTCHours() * ONE_HOUR_MS + now.getUTCMinutes() * ONE_MINUTE_MS + now.getUTCSeconds() * ONE_SECOND_MS;
+    // Round down to tick boundary, then check if it aligns with the interval
+    const rounded = Math.floor(msSinceMidnight / tickMs) * tickMs;
+    return rounded % schedule.intervalMs === 0;
+  }
+
+  if (schedule.type === SCHEDULE_TYPES.daily) {
+    const [hh, mm] = schedule.time.split(":").map(Number);
+    const targetMs = hh * ONE_HOUR_MS + mm * ONE_MINUTE_MS;
+    const msSinceMidnight = now.getUTCHours() * ONE_HOUR_MS + now.getUTCMinutes() * ONE_MINUTE_MS + now.getUTCSeconds() * ONE_SECOND_MS;
+    const rounded = Math.floor(msSinceMidnight / tickMs) * tickMs;
+    return rounded === targetMs;
+  }
+
+  return false;
+}
+
+export function createTaskManager(options?: TaskManagerOptions): ITaskManager {
+  const tickMs = options?.tickMs ?? ONE_MINUTE_MS;
+  const now = options?.now ?? (() => new Date());
+  const registry = new Map<string, TaskDefinition>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  function collectDueTasks(currentTime: Date): {
+    independent: TaskDefinition[];
+    dependent: TaskDefinition[];
+  } {
+    const independent: TaskDefinition[] = [];
+    const dependent: TaskDefinition[] = [];
+    for (const def of registry.values()) {
+      if (def.enabled === false) continue;
+      if (!isDue(currentTime, def.schedule, tickMs)) continue;
+      if (def.dependsOn) {
+        dependent.push(def);
+      } else {
+        independent.push(def);
+      }
+    }
+    return { independent, dependent };
+  }
+
+  async function runAndTrack(def: TaskDefinition, currentTime: Date, succeeded: Set<string>): Promise<void> {
+    try {
+      await def.run({ taskId: def.id, now: currentTime });
+      succeeded.add(def.id);
+    } catch (err) {
+      log.error("task-manager", "task failed", {
+        id: def.id,
+        error: String(err),
+      });
+    }
+  }
+
+  async function runDependentChain(dependent: TaskDefinition[], currentTime: Date, succeeded: Set<string>): Promise<void> {
+    let remaining = [...dependent];
+    let progress = true;
+    while (remaining.length > 0 && progress) {
+      progress = false;
+      const next: TaskDefinition[] = [];
+      for (const def of remaining) {
+        if (!succeeded.has(def.dependsOn!)) {
+          next.push(def);
+          continue;
+        }
+        await runAndTrack(def, currentTime, succeeded);
+        progress = true;
+      }
+      remaining = next;
+    }
+  }
+
+  async function onTick(): Promise<void> {
+    const currentTime = now();
+    const { independent, dependent } = collectDueTasks(currentTime);
+
+    // Per-invocation set — success does not leak across tick() calls.
+    const succeeded = new Set<string>();
+
+    await Promise.all(independent.map((def) => runAndTrack(def, currentTime, succeeded)));
+
+    await runDependentChain(dependent, currentTime, succeeded);
+  }
+
+  return {
+    async tick() {
+      await onTick();
+    },
+
+    registerTask(def: TaskDefinition) {
+      if (registry.has(def.id)) {
+        throw new Error(`[task-manager] Task "${def.id}" is already registered`);
+      }
+      registry.set(def.id, def);
+      log.info("task-manager", "registered", { id: def.id });
+    },
+
+    updateSchedule(taskId: string, schedule: TaskSchedule): boolean {
+      const def = registry.get(taskId);
+      if (!def) return false;
+      def.schedule = schedule;
+      log.info("task-manager", "schedule updated", { id: taskId });
+      return true;
+    },
+
+    removeTask(taskId: string) {
+      if (registry.delete(taskId)) {
+        log.info("task-manager", "removed", { id: taskId });
+      }
+    },
+
+    start() {
+      if (timer) return;
+      timer = setInterval(onTick, tickMs);
+      log.info("task-manager", "started", { tickMs });
+    },
+
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+        log.info("task-manager", "stopped");
+      }
+    },
+
+    listTasks() {
+      return [...registry.values()].map((d) => ({
+        id: d.id,
+        description: d.description,
+        schedule: d.schedule,
+        dependsOn: d.dependsOn,
+      }));
+    },
+  };
+}