circuschief 0.1.0

package/packages/server/src/services/systemMonitor.js

@@ -0,0 +1,281 @@
+import os from 'os';
+import fs from 'fs';
+import { execFile, execFileSync } from 'child_process';
+import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
+import { broadcast } from '../ws/index.js';
+
+// Broadcast interval in milliseconds (5 seconds)
+const BROADCAST_INTERVAL_MS = 5000;
+
+// Interval handle
+let intervalId = null;
+
+// Previous CPU sample for delta computation
+let prevCpus = null;
+
+/**
+ * Compute CPU usage percentage from two cpu samples.
+ * @param {os.CpuInfo[]} prevCpus
+ * @param {os.CpuInfo[]} currCpus
+ * @returns {number} CPU usage percent (0-100)
+ */
+export function computeCpuUsage(prevCpuSamples, currCpuSamples) {
+  if (!prevCpuSamples || !currCpuSamples || prevCpuSamples.length !== currCpuSamples.length) {
+    return 0;
+  }
+
+  let totalIdle = 0;
+  let totalTick = 0;
+
+  for (let i = 0; i < currCpuSamples.length; i++) {
+    const prev = prevCpuSamples[i].times;
+    const curr = currCpuSamples[i].times;
+
+    const idleDelta = curr.idle - prev.idle;
+    const userDelta = curr.user - prev.user;
+    const niceDelta = curr.nice - prev.nice;
+    const sysDelta = curr.sys - prev.sys;
+    const irqDelta = curr.irq - prev.irq;
+
+    const tickDelta = idleDelta + userDelta + niceDelta + sysDelta + irqDelta;
+
+    totalIdle += idleDelta;
+    totalTick += tickDelta;
+  }
+
+  if (totalTick === 0) return 0;
+
+  const usagePercent = ((totalTick - totalIdle) / totalTick) * 100;
+  return Math.round(usagePercent * 10) / 10;
+}
+
+/**
+ * Get available memory bytes using platform-specific methods.
+ *
+ * os.freemem() only reports truly "free" memory, ignoring reclaimable
+ * caches and buffers. On macOS especially, this makes memory appear nearly
+ * exhausted even when the system is not under pressure.
+ *
+ * - macOS: uses vm_stat to sum free + purgeable + speculative pages
+ * - Linux: reads MemAvailable from /proc/meminfo
+ * - Fallback: os.freemem()
+ *
+ * @returns {number} Available memory in bytes
+ */
+export function getAvailableMemoryBytes() {
+  const platform = os.platform();
+
+  if (platform === 'darwin') {
+    try {
+      const stdout = execFileSync('vm_stat', { encoding: 'utf8', timeout: 3000 });
+      return parseVmStatOutput(stdout);
+    } catch {
+      return os.freemem();
+    }
+  }
+
+  if (platform === 'linux') {
+    try {
+      const content = fs.readFileSync('/proc/meminfo', 'utf8');
+      return parseMemInfoOutput(content);
+    } catch {
+      return os.freemem();
+    }
+  }
+
+  return os.freemem();
+}
+
+/**
+ * Parse macOS vm_stat output to compute available memory bytes.
+ *
+ * macOS categorises physical pages as:
+ *   - free:        truly unused
+ *   - inactive:    not recently accessed, reclaimable immediately
+ *   - speculative: speculatively allocated, reclaimable
+ *   - purgeable:   marked purgeable by apps, reclaimable
+ *   - active:      recently accessed by running processes
+ *   - wired:       locked by the kernel, cannot be paged out
+ *   - compressed:  compressed in the compressor
+ *
+ * "Available" = free + inactive + purgeable + speculative
+ * This matches what macOS considers available (not under pressure).
+ *
+ * @param {string} stdout - Output from vm_stat command
+ * @returns {number} Available memory in bytes
+ */
+export function parseVmStatOutput(stdout) {
+  if (!stdout || typeof stdout !== 'string') return os.freemem();
+
+  // First line contains page size, e.g. "Mach Virtual Memory Statistics: (page size of 16384 bytes)"
+  const pageSizeMatch = stdout.match(/page size of (\d+) bytes/);
+  const pageSize = pageSizeMatch ? parseInt(pageSizeMatch[1], 10) : 16384;
+
+  // Parse page counts - vm_stat format: "Pages free:    123456."
+  const getValue = (label) => {
+    const match = stdout.match(new RegExp(`${label}:\\s+(\\d+)`));
+    return match ? parseInt(match[1], 10) : 0;
+  };
+
+  const free = getValue('Pages free');
+  const inactive = getValue('Pages inactive');
+  const purgeable = getValue('Pages purgeable');
+  const speculative = getValue('Pages speculative');
+
+  const availableBytes = (free + inactive + purgeable + speculative) * pageSize;
+
+  // Sanity check: if result is 0 or unreasonably small, fall back
+  if (availableBytes <= 0) return os.freemem();
+
+  return availableBytes;
+}
+
+/**
+ * Parse Linux /proc/meminfo to get MemAvailable.
+ *
+ * @param {string} content - Contents of /proc/meminfo
+ * @returns {number} Available memory in bytes
+ */
+export function parseMemInfoOutput(content) {
+  if (!content || typeof content !== 'string') return os.freemem();
+
+  const match = content.match(/MemAvailable:\s+(\d+)\s+kB/);
+  if (!match) return os.freemem();
+
+  return parseInt(match[1], 10) * 1024;
+}
+
+/**
+ * Compute memory metrics from OS.
+ * @param {number} [totalBytes] - Total memory bytes (defaults to os.totalmem()); injectable for testing
+ * @param {number} [availableBytes] - Available memory bytes (defaults to platform-aware available memory); injectable for testing
+ * @returns {{ usedPercent: number, usedGB: number, totalGB: number }}
+ */
+export function computeMemoryMetrics(totalBytes = os.totalmem(), availableBytes = getAvailableMemoryBytes()) {
+  const usedBytes = totalBytes - availableBytes;
+
+  const totalGB = Math.round((totalBytes / (1024 ** 3)) * 10) / 10;
+  const usedGB = Math.round((usedBytes / (1024 ** 3)) * 10) / 10;
+  const usedPercent = Math.round((usedBytes / totalBytes) * 1000) / 10;
+
+  return { usedPercent, usedGB, totalGB };
+}
+
+/**
+ * Parse `df -k /` output to extract disk metrics.
+ * @param {string} stdout
+ * @returns {{ usedPercent: number, freeGB: number, totalGB: number } | null}
+ */
+export function parseDfOutput(stdout) {
+  if (!stdout || typeof stdout !== 'string') return null;
+
+  const lines = stdout.trim().split('\n');
+  // df output: header line + data line(s)
+  // We want the second line (index 1)
+  if (lines.length < 2) return null;
+
+  const dataLine = lines[1].trim();
+  if (!dataLine) return null;
+
+  // df -k columns: Filesystem 1K-blocks Used Available Use% Mounted-on
+  const parts = dataLine.split(/\s+/);
+  if (parts.length < 5) return null;
+
+  const totalKB = parseInt(parts[1], 10);
+  const usedKB = parseInt(parts[2], 10);
+  const availKB = parseInt(parts[3], 10);
+
+  if (isNaN(totalKB) || isNaN(usedKB) || isNaN(availKB) || totalKB === 0) return null;
+
+  const totalGB = Math.round((totalKB / (1024 ** 2)) * 10) / 10;
+  const freeGB = Math.round((availKB / (1024 ** 2)) * 10) / 10;
+  // Use (total - available) instead of "used" column for usedPercent.
+  // On macOS APFS, the Used column only reports one volume snapshot, not total usage.
+  // On Linux, Used + Available ≠ Total due to reserved blocks.
+  const effectiveUsedKB = totalKB - availKB;
+  const usedPercent = Math.round((effectiveUsedKB / totalKB) * 1000) / 10;
+
+  return { usedPercent, freeGB, totalGB };
+}
+
+/**
+ * Collect disk metrics using df command.
+ * Returns null if df is unavailable or fails.
+ * @returns {Promise<{ usedPercent: number, freeGB: number, totalGB: number } | null>}
+ */
+async function collectDiskMetrics() {
+  return new Promise((resolve) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+
+    execFile('df', ['-k', '/'], { signal: controller.signal }, (error, stdout) => {
+      clearTimeout(timeout);
+      if (error) {
+        resolve(null);
+        return;
+      }
+      resolve(parseDfOutput(stdout));
+    });
+  });
+}
+
+/**
+ * Collect and broadcast system metrics.
+ */
+async function collectAndBroadcast() {
+  // CPU: sample current, compute delta from previous
+  const currCpus = os.cpus();
+  const cpuUsagePercent = computeCpuUsage(prevCpus, currCpus);
+  prevCpus = currCpus;
+
+  // Memory
+  const memory = computeMemoryMetrics();
+
+  // Disk (may be null on failure or Windows)
+  const disk = await collectDiskMetrics();
+
+  const payload = {
+    cpu: {
+      usagePercent: cpuUsagePercent,
+      coreCount: currCpus.length,
+      model: currCpus[0]?.model || 'Unknown',
+    },
+    memory,
+    disk,
+  };
+
+  broadcast(WS_MESSAGE_TYPES.SYSTEM_METRICS, payload);
+}
+
+/**
+ * Start the system monitor service.
+ * Broadcasts system metrics every 5 seconds.
+ */
+export function start() {
+  if (intervalId) {
+    console.log('[SystemMonitor] Already running');
+    return;
+  }
+
+  console.log('[SystemMonitor] Starting system metrics broadcast');
+
+  // Take initial CPU sample before first interval fires
+  prevCpus = os.cpus();
+
+  intervalId = setInterval(collectAndBroadcast, BROADCAST_INTERVAL_MS);
+}
+
+/**
+ * Stop the system monitor service.
+ */
+export function stop() {
+  if (intervalId) {
+    clearInterval(intervalId);
+    intervalId = null;
+    prevCpus = null;
+    console.log('[SystemMonitor] Stopped system metrics broadcast');
+  }
+}
+
+// Export for testing
+export { BROADCAST_INTERVAL_MS, collectAndBroadcast };

package/packages/server/src/services/templateTriggerService.js

@@ -0,0 +1,197 @@
+import { Liquid } from 'liquidjs';
+import { sessions, sessionTemplates, sessionSummaries, projects } from '../database.js';
+import { setupGitForSession } from './gitSessionSetup.js';
+import { runSession } from './sessionManager.js';
+import { broadcastToProject } from '../websocket.js';
+import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
+
+const liquid = new Liquid();
+
+/**
+ * Get the root session (the original session that started a template chain)
+ * @param {Object} session - The current session
+ * @returns {Object} The root session (or the current session if it has no parent)
+ */
+export function getRootSession(session) {
+  let current = session;
+  while (current.parentSessionId) {
+    const parent = sessions.getById(current.parentSessionId);
+    if (!parent) break;
+    current = parent;
+  }
+  return current;
+}
+
+/**
+ * Build a template context object for a session and its summary.
+ */
+function buildSessionContext(session, summary) {
+  return {
+    id: session.id,
+    name: session.name,
+    status: session.status,
+    summary: summary?.fullSummary || summary?.shortSummary || 'No summary available',
+    shortSummary: summary?.shortSummary || 'No summary available',
+    fullSummary: summary?.fullSummary || 'No summary available',
+    keyActions: summary?.keyActions || [],
+    filesModified: summary?.filesModified || [],
+    outcome: summary?.outcome || session.status,
+  };
+}
+
+/**
+ * Render a template prompt with parent session and root session context
+ * @param {string} templatePrompt - The Liquid template string
+ * @param {{ parentSession: Object, parentSummary: Object|null, rootSession: Object, rootSummary: Object|null }} sessionContext - Session context objects
+ * @returns {Promise<string>} The rendered prompt
+ */
+export async function renderTemplatePrompt(templatePrompt, sessionContext) {
+  const { parentSession, parentSummary, rootSession, rootSummary } = sessionContext;
+  const context = {
+    parentSession: buildSessionContext(parentSession, parentSummary),
+    rootSession: buildSessionContext(rootSession, rootSummary),
+  };
+
+  return liquid.parseAndRender(templatePrompt, context);
+}
+
+/**
+ * Derive session settings from template and root session.
+ * Template values take precedence if set, otherwise inherit from root.
+ */
+function deriveSessionSettings(template, rootSession) {
+  return {
+    thinkingEnabled: template.thinkingEnabled !== null ? template.thinkingEnabled : rootSession.thinkingEnabled,
+    gitBranch: template.gitBranch || rootSession.gitBranch,
+    gitMode: template.gitMode || null,
+    model: template.model !== null ? template.model : rootSession.model,
+    mode: template.mode !== null ? template.mode : rootSession.mode,
+    effortLevel: template.effortLevel !== null ? template.effortLevel : rootSession.effortLevel,
+    // Inherit rescheduling settings from root session
+    autoRescheduleEnabled: rootSession.autoRescheduleEnabled,
+    rescheduleOnTokenLimit: rootSession.rescheduleOnTokenLimit,
+    rescheduleOnServiceError: rootSession.rescheduleOnServiceError,
+    rescheduleDelayMinutes: rootSession.rescheduleDelayMinutes,
+    rescheduleAtTokenCount: rootSession.rescheduleAtTokenCount,
+    maxRescheduleCount: rootSession.maxRescheduleCount,
+    maxTotalTokens: rootSession.maxTotalTokens,
+  };
+}
+
+/**
+ * Resolve the working directory for a new template-triggered session.
+ * Inherits the parent worktree if available, otherwise sets up git normally.
+ * @param {Object} parentSession - The parent session
+ * @param {Object} project - The project
+ * @param {Object} settings - Derived session settings
+ * @param {string} newSessionId - The new session ID
+ * @returns {Promise<{workingDirectory: string, gitWorktree: string|null}>}
+ */
+async function resolveWorkingDirectory(parentSession, project, settings, newSessionId) {
+  if (parentSession.gitWorktree) {
+    console.log(`Template trigger: Inheriting parent worktree: ${parentSession.gitWorktree}`);
+    return { workingDirectory: parentSession.gitWorktree, gitWorktree: parentSession.gitWorktree };
+  }
+
+  const gitSetup = await setupGitForSession({
+    projectDir: project.workingDirectory,
+    gitMode: settings.gitMode,
+    gitBranch: settings.gitBranch,
+    sessionId: newSessionId,
+  });
+  return { workingDirectory: gitSetup.workingDirectory, gitWorktree: gitSetup.gitWorktree };
+}
+
+/**
+ * Check if a session should trigger its next template and do so
+ * Called when a session completes (status changes to completed, error, or stopped)
+ * @param {string} sessionId - The session that just completed
+ */
+export async function checkAndTriggerNextTemplate(sessionId) {
+  const session = sessions.getById(sessionId);
+  if (!session) {
+    console.warn(`Template trigger: Session ${sessionId} not found`);
+    return;
+  }
+
+  if (!session.nextTemplateId) {
+    return;
+  }
+
+  const template = sessionTemplates.getById(session.nextTemplateId);
+  if (!template) {
+    console.warn(`Template trigger: Template ${session.nextTemplateId} not found for session ${sessionId}`);
+    return;
+  }
+
+  const project = projects.getById(session.projectId);
+  if (!project) {
+    console.warn(`Template trigger: Project ${session.projectId} not found for session ${sessionId}`);
+    return;
+  }
+
+  console.log(`Template trigger: Triggering template "${template.name}" after session "${session.name}"`);
+
+  try {
+    const parentSummary = sessionSummaries.getBySessionId(sessionId);
+    const rootSession = getRootSession(session);
+    const rootSummary = sessionSummaries.getBySessionId(rootSession.id);
+
+    const renderedPrompt = await renderTemplatePrompt(template.prompt, { parentSession: session, parentSummary, rootSession, rootSummary });
+    const settings = deriveSessionSettings(template, rootSession);
+    const newSessionName = `${template.name} (from: ${session.name})`;
+
+    const newSession = sessions.create(
+      session.projectId,
+      newSessionName,
+      renderedPrompt,
+      {
+        mode: settings.mode,
+        thinkingEnabled: settings.thinkingEnabled,
+        gitBranch: settings.gitBranch,
+        parentSessionId: null,
+        status: 'starting',
+        model: settings.model,
+        effortLevel: settings.effortLevel,
+      }
+    );
+
+    sessions.update(newSession.id, {
+      parentSessionId: session.id,
+      nextTemplateId: template.nextTemplateId || null,
+      autoRescheduleEnabled: settings.autoRescheduleEnabled,
+      rescheduleOnTokenLimit: settings.rescheduleOnTokenLimit,
+      rescheduleOnServiceError: settings.rescheduleOnServiceError,
+      rescheduleDelayMinutes: settings.rescheduleDelayMinutes,
+      rescheduleAtTokenCount: settings.rescheduleAtTokenCount,
+      maxRescheduleCount: settings.maxRescheduleCount,
+      maxTotalTokens: settings.maxTotalTokens,
+    });
+
+    const { workingDirectory, gitWorktree } = await resolveWorkingDirectory(session, project, settings, newSession.id);
+
+    if (gitWorktree) {
+      sessions.update(newSession.id, { gitWorktree });
+    }
+
+    const updatedSession = sessions.getById(newSession.id);
+    broadcastToProject(session.projectId, WS_MESSAGE_TYPES.SESSION_CREATED, {
+      projectId: session.projectId,
+      session: updatedSession,
+    });
+
+    runSession(newSession.id, renderedPrompt, workingDirectory, { systemPrompt: project.systemPrompt, model: settings.model }).catch((error) => {
+      console.error(`Template trigger: Error running session ${newSession.id}:`, error);
+      const errorSession = sessions.update(newSession.id, { status: 'error', error: error.message });
+      broadcastToProject(session.projectId, WS_MESSAGE_TYPES.SESSION_UPDATED, {
+        projectId: session.projectId,
+        sessionId: newSession.id,
+        session: errorSession,
+      });
+    });
+
+    console.log(`Template trigger: Created and started session ${newSession.id}`);
+  } catch (error) {
+    console.error(`Template trigger: Failed to trigger template for session ${sessionId}:`, error);
+  }
+}

package/packages/server/src/services/terminalOutput.js

@@ -0,0 +1,160 @@
+/**
+ * Strip ANSI escape codes from text
+ * Removes all CSI (Control Sequence Introducer) sequences:
+ * - SGR codes: \x1b[...m (colors, bold, italic, etc.)
+ * - Cursor movement: \x1b[1A, \x1b[2B, etc.
+ * - Line/screen clearing: \x1b[2K, \x1b[0J, etc.
+ * - Other CSI sequences: \x1b[...H, \x1b[...J, etc.
+ *
+ * @param {string} text - Text potentially containing ANSI codes
+ * @returns {string} Text with all ANSI codes removed
+ */
+export function stripAnsiCodes(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+  // Match all CSI sequences: ESC [ <params> <final-char>
+  // This covers colors, cursor movement, line clearing, and other terminal control sequences
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+}
+
+/**
+ * Terminal output processor that simulates cursor control behavior
+ *
+ * When tools like yarn run in TTY mode, they use cursor control sequences to create
+ * animated progress displays. For example:
+ *   \x1b[2K\x1b[1G[] 0/576    <- clear line, go to column 1, print progress
+ *   \x1b[2K\x1b[1G[] 136/576  <- clear line, go to column 1, print NEW progress
+ *
+ * On a real terminal, the second line overwrites the first. But when we just strip
+ * the codes, we get "[] 0/576[] 136/576" concatenated together.
+ *
+ * This processor simulates the terminal behavior by:
+ * 1. Maintaining a "current line" buffer (content since last newline)
+ * 2. When we see \x1b[2K (clear line), we clear the current line buffer
+ * 3. When we see \x1b[1G (cursor to column 1), we clear the current line buffer
+ * 4. When we see \r (carriage return), we clear the current line buffer
+ * 5. When we see \n, we flush the current line and start fresh
+ * 6. All ANSI escape codes are stripped from output
+ */
+export class TerminalOutputProcessor {
+  constructor() {
+    /** @type {string} Content on the current line (since last newline) */
+    this.currentLine = '';
+  }
+
+  /**
+   * Handle a CSI (Control Sequence Introducer) command
+   * Returns true if the current line should be cleared
+   * @param {string} cmd - The command character
+   * @param {string} params - The parameters string
+   * @returns {boolean} Whether to clear the current line
+   */
+  #shouldClearLineForCSI(cmd, params) {
+    // Erase in Line: [0K = to end, [1K = to start, [2K = entire line
+    if (cmd === 'K') return true;
+    // Cursor Character Absolute: [1G = go to column 1 (start of line)
+    if (cmd === 'G' && (params === '' || params === '1')) return true;
+    // Cursor Position: [n;mH or [n;mf moves cursor to row n, column m
+    if (cmd === 'H' || cmd === 'f') return true;
+    // Cursor movement: A=up, B=down, C=right, D=left
+    if (cmd === 'A' || cmd === 'B' || cmd === 'C' || cmd === 'D') return true;
+    // Erase in Display: [0J = to end, [1J = to start, [2J = entire screen
+    if (cmd === 'J') return true;
+    return false;
+  }
+
+  /**
+   * Try to parse and handle a CSI escape sequence starting at position i.
+   * Returns the new index past the sequence, or -1 if not a complete CSI sequence.
+   * @param {string} chunk
+   * @param {number} i - current index (pointing at ESC)
+   * @returns {number} new index past the sequence, or -1
+   */
+  #handleCSISequence(chunk, i) {
+    if (chunk[i] !== '\x1b' || chunk[i + 1] !== '[') return -1;
+    // Parse the CSI sequence: ESC [ <params> <command>
+    let j = i + 2;
+    while (j < chunk.length && /[0-9;?]/.test(chunk[j])) {
+      j++;
+    }
+    if (j >= chunk.length) return -1;
+
+    const cmd = chunk[j];
+    const params = chunk.slice(i + 2, j);
+
+    // Handle cursor control sequences that affect line content
+    if (this.#shouldClearLineForCSI(cmd, params)) this.currentLine = '';
+    // All other sequences (including color codes 'm') are just stripped
+
+    return j + 1;
+  }
+
+  /**
+   * Process a chunk of terminal output, simulating cursor control behavior
+   *
+   * @param {string} chunk - Raw terminal output chunk
+   * @returns {string} Processed output with cursor behavior simulated and ANSI codes stripped
+   */
+  process(chunk) {
+    if (!chunk || typeof chunk !== 'string') {
+      return '';
+    }
+
+    let output = '';
+    let i = 0;
+
+    while (i < chunk.length) {
+      // Check for ESC sequence
+      const csiEnd = this.#handleCSISequence(chunk, i);
+      if (csiEnd >= 0) {
+        i = csiEnd;
+        continue;
+      }
+
+      // Handle carriage return - go to start of line (used for overwriting)
+      if (chunk[i] === '\r') {
+        // Don't clear if next char is \n (normal line ending)
+        if (chunk[i + 1] !== '\n') {
+          this.currentLine = '';
+        }
+        i++;
+        continue;
+      }
+
+      // Handle newline - flush current line and start fresh
+      if (chunk[i] === '\n') {
+        output += `${this.currentLine  }\n`;
+        this.currentLine = '';
+        i++;
+        continue;
+      }
+
+      // Regular character - add to current line
+      this.currentLine += chunk[i];
+      i++;
+    }
+
+    return output;
+  }
+
+  /**
+   * Flush any remaining content in the current line buffer
+   * Call this when the stream ends to get the final incomplete line
+   *
+   * @returns {string} Any remaining content
+   */
+  flush() {
+    const remaining = this.currentLine;
+    this.currentLine = '';
+    return remaining;
+  }
+
+  /**
+   * Reset the processor state
+   */
+  reset() {
+    this.currentLine = '';
+  }
+}

package/packages/server/src/services/todoStore.js

@@ -0,0 +1,58 @@
+import { todos, conversations } from '../database.js';
+import { broadcastToSession } from '../websocket.js';
+import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
+
+/**
+ * Update todos for a conversation (replaces all existing todos for that conversation)
+ * Called when Claude executes TodoWrite
+ * @param {string} sessionId
+ * @param {string} conversationId
+ * @param {Array<{content: string, status: string}>} todoList
+ * @returns {Array}
+ */
+export function updateTodos(sessionId, conversationId, todoList) {
+  const updatedTodos = todos.replaceAllForConversation(sessionId, conversationId, todoList);
+  broadcastToSession(sessionId, WS_MESSAGE_TYPES.TODOS_UPDATE, {
+    sessionId,
+    conversationId,
+    todos: updatedTodos,
+  });
+  return updatedTodos;
+}
+
+/**
+ * Get all todos for a conversation
+ * @param {string} conversationId
+ * @returns {Array}
+ */
+export function getTodosByConversation(conversationId) {
+  return todos.getByConversationId(conversationId);
+}
+
+/**
+ * Get all todos for the active conversation of a session
+ * Falls back to empty array if no active conversation
+ * @param {string} sessionId
+ * @returns {Array}
+ */
+export function getTodosForSession(sessionId) {
+  const activeConv = conversations.getActiveBySessionId(sessionId);
+  if (activeConv) {
+    return todos.getByConversationId(activeConv.id);
+  }
+  return [];
+}
+
+/**
+ * Clear all todos for a conversation
+ * @param {string} sessionId
+ * @param {string} conversationId
+ */
+export function clearTodos(sessionId, conversationId) {
+  todos.deleteByConversationId(conversationId);
+  broadcastToSession(sessionId, WS_MESSAGE_TYPES.TODOS_UPDATE, {
+    sessionId,
+    conversationId,
+    todos: [],
+  });
+}