create-ironclaws 1.0.0

package/template/src/task-scheduler.ts

@@ -0,0 +1,290 @@
+import { ChildProcess } from 'child_process';
+import { CronExpressionParser } from 'cron-parser';
+import fs from 'fs';
+
+import { ASSISTANT_NAME, SCHEDULER_POLL_INTERVAL, TASK_CLOSE_DELAY_MS, TIMEZONE } from './config.js';
+import {
+  ContainerOutput,
+  runContainerAgent,
+  writeTasksSnapshot,
+} from './container-runner.js';
+import {
+  getAllTasks,
+  getDueTasks,
+  getTaskById,
+  logTaskRun,
+  updateTask,
+  updateTaskAfterRun,
+} from './db.js';
+import { GroupQueue } from './group-queue.js';
+import { resolveGroupFolderPath } from './group-folder.js';
+import { logger } from './logger.js';
+import { RegisteredGroup, ScheduledTask } from './types.js';
+
+/**
+ * Compute the next run time for a recurring task, anchored to the
+ * task's scheduled time rather than Date.now() to prevent cumulative
+ * drift on interval-based tasks.
+ *
+ * Co-authored-by: @community-pr-601
+ */
+export function computeNextRun(task: ScheduledTask): string | null {
+  if (task.schedule_type === 'once') return null;
+
+  const now = Date.now();
+
+  if (task.schedule_type === 'cron') {
+    const interval = CronExpressionParser.parse(task.schedule_value, {
+      tz: TIMEZONE,
+    });
+    return interval.next().toISOString();
+  }
+
+  if (task.schedule_type === 'interval') {
+    const ms = parseInt(task.schedule_value, 10);
+    if (!ms || ms <= 0) {
+      // Guard against malformed interval that would cause an infinite loop
+      logger.warn(
+        { taskId: task.id, value: task.schedule_value },
+        'Invalid interval value',
+      );
+      return new Date(now + 60_000).toISOString();
+    }
+    // Anchor to the scheduled time, not now, to prevent drift.
+    // Skip past any missed intervals so we always land in the future.
+    let next = new Date(task.next_run!).getTime() + ms;
+    while (next <= now) {
+      next += ms;
+    }
+    return new Date(next).toISOString();
+  }
+
+  return null;
+}
+
+export interface SchedulerDependencies {
+  registeredGroups: () => Record<string, RegisteredGroup>;
+  getSessions: () => Record<string, string>;
+  queue: GroupQueue;
+  onProcess: (
+    groupJid: string,
+    proc: ChildProcess,
+    containerName: string,
+    groupFolder: string,
+  ) => void;
+  sendMessage: (jid: string, text: string) => Promise<void>;
+}
+
+async function runTask(
+  task: ScheduledTask,
+  deps: SchedulerDependencies,
+): Promise<void> {
+  const startTime = Date.now();
+  let groupDir: string;
+  try {
+    groupDir = resolveGroupFolderPath(task.group_folder);
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    // Stop retry churn for malformed legacy rows.
+    updateTask(task.id, { status: 'paused' });
+    logger.error(
+      { taskId: task.id, groupFolder: task.group_folder, error },
+      'Task has invalid group folder',
+    );
+    logTaskRun({
+      task_id: task.id,
+      run_at: new Date().toISOString(),
+      duration_ms: Date.now() - startTime,
+      status: 'error',
+      result: null,
+      error,
+    });
+    return;
+  }
+  fs.mkdirSync(groupDir, { recursive: true });
+
+  // Advance next_run immediately so getDueTasks() won't re-find this task
+  // on the next scheduler tick while the container is still running.
+  const nextRun = computeNextRun(task);
+  updateTask(task.id, { next_run: nextRun ?? undefined });
+
+  logger.info(
+    { taskId: task.id, group: task.group_folder },
+    'Running scheduled task',
+  );
+
+  const groups = deps.registeredGroups();
+  const group = Object.values(groups).find(
+    (g) => g.folder === task.group_folder,
+  );
+
+  if (!group) {
+    logger.error(
+      { taskId: task.id, groupFolder: task.group_folder },
+      'Group not found for task',
+    );
+    logTaskRun({
+      task_id: task.id,
+      run_at: new Date().toISOString(),
+      duration_ms: Date.now() - startTime,
+      status: 'error',
+      result: null,
+      error: `Group not found: ${task.group_folder}`,
+    });
+    return;
+  }
+
+  // Update tasks snapshot for container to read (filtered by group)
+  const isMain = group.isMain === true;
+  const tasks = getAllTasks();
+  writeTasksSnapshot(
+    task.group_folder,
+    isMain,
+    tasks.map((t) => ({
+      id: t.id,
+      groupFolder: t.group_folder,
+      prompt: t.prompt,
+      script: t.script,
+      schedule_type: t.schedule_type,
+      schedule_value: t.schedule_value,
+      status: t.status,
+      next_run: t.next_run,
+    })),
+  );
+
+  let result: string | null = null;
+  let error: string | null = null;
+
+  // For group context mode, use the group's current session
+  const sessions = deps.getSessions();
+  const sessionId =
+    task.context_mode === 'group' ? sessions[task.group_folder] : undefined;
+
+  // After the task produces a result, close the container promptly.
+  // Tasks are single-turn — no need to wait IDLE_TIMEOUT (30 min) for the
+  // query loop to time out. A short delay handles any final MCP calls.
+  // TASK_CLOSE_DELAY_MS imported from config (default 10s, env-configurable)
+  let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const scheduleClose = () => {
+    if (closeTimer) return; // already scheduled
+    closeTimer = setTimeout(() => {
+      logger.debug({ taskId: task.id }, 'Closing task container after result');
+      deps.queue.closeStdin(task.chat_jid);
+    }, TASK_CLOSE_DELAY_MS);
+  };
+
+  try {
+    const output = await runContainerAgent(
+      group,
+      {
+        prompt: task.prompt,
+        sessionId,
+        groupFolder: task.group_folder,
+        chatJid: task.chat_jid,
+        isMain,
+        isScheduledTask: true,
+        assistantName: ASSISTANT_NAME,
+        script: task.script || undefined,
+      },
+      (proc, containerName) =>
+        deps.onProcess(task.chat_jid, proc, containerName, task.group_folder),
+      async (streamedOutput: ContainerOutput) => {
+        if (streamedOutput.result) {
+          result = streamedOutput.result;
+          // Forward result to user unless task is marked silent
+          if (!task.silent) {
+            await deps.sendMessage(task.chat_jid, streamedOutput.result);
+          }
+          scheduleClose();
+        }
+        if (streamedOutput.status === 'success') {
+          deps.queue.notifyIdle(task.chat_jid);
+          scheduleClose(); // Close promptly even when result is null (e.g. IPC-only tasks)
+        }
+        if (streamedOutput.status === 'error') {
+          error = streamedOutput.error || 'Unknown error';
+        }
+      },
+    );
+
+    if (closeTimer) clearTimeout(closeTimer);
+
+    if (output.status === 'error') {
+      error = output.error || 'Unknown error';
+    } else if (output.result) {
+      // Result was already forwarded to the user via the streaming callback above
+      result = output.result;
+    }
+
+    logger.info(
+      { taskId: task.id, durationMs: Date.now() - startTime },
+      'Task completed',
+    );
+  } catch (err) {
+    if (closeTimer) clearTimeout(closeTimer);
+    error = err instanceof Error ? err.message : String(err);
+    logger.error({ taskId: task.id, error }, 'Task failed');
+  }
+
+  const durationMs = Date.now() - startTime;
+
+  logTaskRun({
+    task_id: task.id,
+    run_at: new Date().toISOString(),
+    duration_ms: durationMs,
+    status: error ? 'error' : 'success',
+    result,
+    error,
+  });
+
+  const resultSummary = error
+    ? `Error: ${error}`
+    : result
+      ? result.slice(0, 200)
+      : 'Completed';
+  updateTaskAfterRun(task.id, nextRun, resultSummary);
+}
+
+let schedulerRunning = false;
+
+export function startSchedulerLoop(deps: SchedulerDependencies): void {
+  if (schedulerRunning) {
+    logger.debug('Scheduler loop already running, skipping duplicate start');
+    return;
+  }
+  schedulerRunning = true;
+  logger.info('Scheduler loop started');
+
+  const loop = async () => {
+    try {
+      const dueTasks = getDueTasks();
+      if (dueTasks.length > 0) {
+        logger.info({ count: dueTasks.length }, 'Found due tasks');
+      }
+
+      for (const task of dueTasks) {
+        // Re-check task status in case it was paused/cancelled
+        const currentTask = getTaskById(task.id);
+        if (!currentTask || currentTask.status !== 'active') {
+          continue;
+        }
+
+        deps.queue.enqueueTask(currentTask.chat_jid, currentTask.id, () =>
+          runTask(currentTask, deps),
+        );
+      }
+    } catch (err) {
+      logger.error({ err }, 'Error in scheduler loop');
+    }
+
+    setTimeout(loop, SCHEDULER_POLL_INTERVAL);
+  };
+
+  loop();
+}
+
+/** @internal - for tests only. */
+export function _resetSchedulerLoopForTests(): void {
+  schedulerRunning = false;
+}

package/template/src/timezone.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  formatLocalTime,
+  isValidTimezone,
+  resolveTimezone,
+} from './timezone.js';
+
+// --- formatLocalTime ---
+
+describe('formatLocalTime', () => {
+  it('converts UTC to local time display', () => {
+    // 2026-02-04T18:30:00Z in America/New_York (EST, UTC-5) = 1:30 PM
+    const result = formatLocalTime(
+      '2026-02-04T18:30:00.000Z',
+      'America/New_York',
+    );
+    expect(result).toContain('1:30');
+    expect(result).toContain('PM');
+    expect(result).toContain('Feb');
+    expect(result).toContain('2026');
+  });
+
+  it('handles different timezones', () => {
+    // Same UTC time should produce different local times
+    const utc = '2026-06-15T12:00:00.000Z';
+    const ny = formatLocalTime(utc, 'America/New_York');
+    const tokyo = formatLocalTime(utc, 'Asia/Tokyo');
+    // NY is UTC-4 in summer (EDT), Tokyo is UTC+9
+    expect(ny).toContain('8:00');
+    expect(tokyo).toContain('9:00');
+  });
+
+  it('does not throw on invalid timezone, falls back to UTC', () => {
+    expect(() =>
+      formatLocalTime('2026-01-01T00:00:00.000Z', 'IST-2'),
+    ).not.toThrow();
+    const result = formatLocalTime('2026-01-01T12:00:00.000Z', 'IST-2');
+    // Should format as UTC (noon UTC = 12:00 PM)
+    expect(result).toContain('12:00');
+    expect(result).toContain('PM');
+  });
+});
+
+describe('isValidTimezone', () => {
+  it('accepts valid IANA identifiers', () => {
+    expect(isValidTimezone('America/New_York')).toBe(true);
+    expect(isValidTimezone('UTC')).toBe(true);
+    expect(isValidTimezone('Asia/Tokyo')).toBe(true);
+    expect(isValidTimezone('Asia/Jerusalem')).toBe(true);
+  });
+
+  it('rejects invalid timezone strings', () => {
+    expect(isValidTimezone('IST-2')).toBe(false);
+    expect(isValidTimezone('XYZ+3')).toBe(false);
+  });
+
+  it('rejects empty and garbage strings', () => {
+    expect(isValidTimezone('')).toBe(false);
+    expect(isValidTimezone('NotATimezone')).toBe(false);
+  });
+});
+
+describe('resolveTimezone', () => {
+  it('returns the timezone if valid', () => {
+    expect(resolveTimezone('America/New_York')).toBe('America/New_York');
+  });
+
+  it('falls back to UTC for invalid timezone', () => {
+    expect(resolveTimezone('IST-2')).toBe('UTC');
+    expect(resolveTimezone('')).toBe('UTC');
+  });
+});

package/template/src/timezone.ts

@@ -0,0 +1,37 @@
+/**
+ * Check whether a timezone string is a valid IANA identifier
+ * that Intl.DateTimeFormat can use.
+ */
+export function isValidTimezone(tz: string): boolean {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the given timezone if valid IANA, otherwise fall back to UTC.
+ */
+export function resolveTimezone(tz: string): string {
+  return isValidTimezone(tz) ? tz : 'UTC';
+}
+
+/**
+ * Convert a UTC ISO timestamp to a localized display string.
+ * Uses the Intl API (no external dependencies).
+ * Falls back to UTC if the timezone is invalid.
+ */
+export function formatLocalTime(utcIso: string, timezone: string): string {
+  const date = new Date(utcIso);
+  return date.toLocaleString('en-US', {
+    timeZone: resolveTimezone(timezone),
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  });
+}

package/template/src/types.ts

@@ -0,0 +1,114 @@
+export interface AdditionalMount {
+  hostPath: string; // Absolute path on host (supports ~ for home)
+  containerPath?: string; // Optional — defaults to basename of hostPath. Mounted at /workspace/extra/{value}
+  readonly?: boolean; // Default: true for safety
+  worktree?: boolean; // If true, create a per-group git worktree instead of bind-mounting the repo directly
+}
+
+/**
+ * Mount Allowlist - Security configuration for additional mounts
+ * This file should be stored at ~/.config/nanoclaw/mount-allowlist.json
+ * and is NOT mounted into any container, making it tamper-proof from agents.
+ */
+export interface MountAllowlist {
+  // Directories that can be mounted into containers
+  allowedRoots: AllowedRoot[];
+  // Glob patterns for paths that should never be mounted (e.g., ".ssh", ".gnupg")
+  blockedPatterns: string[];
+  // If true, non-main groups can only mount read-only regardless of config
+  nonMainReadOnly: boolean;
+}
+
+export interface AllowedRoot {
+  // Absolute path or ~ for home (e.g., "~/projects", "/var/repos")
+  path: string;
+  // Whether read-write mounts are allowed under this root
+  allowReadWrite: boolean;
+  // Optional description for documentation
+  description?: string;
+}
+
+export interface ContainerConfig {
+  additionalMounts?: AdditionalMount[];
+  timeout?: number; // Default: 300000 (5 minutes)
+  noThreading?: boolean; // If true, always post to channel (never in threads)
+}
+
+export interface RegisteredGroup {
+  name: string;
+  folder: string;
+  trigger: string;
+  added_at: string;
+  containerConfig?: ContainerConfig;
+  requiresTrigger?: boolean; // Default: true for groups, false for solo chats
+  isMain?: boolean; // True for the main control group (no trigger, elevated privileges)
+}
+
+export interface NewMessage {
+  id: string;
+  chat_jid: string;
+  sender: string;
+  sender_name: string;
+  sender_email?: string;
+  content: string;
+  timestamp: string;
+  is_from_me?: boolean;
+  is_bot_message?: boolean;
+}
+
+export interface ScheduledTask {
+  id: string;
+  group_folder: string;
+  chat_jid: string;
+  prompt: string;
+  script?: string | null;
+  schedule_type: 'cron' | 'interval' | 'once';
+  schedule_value: string;
+  context_mode: 'group' | 'isolated';
+  next_run: string | null;
+  last_run: string | null;
+  last_result: string | null;
+  status: 'active' | 'paused' | 'completed';
+  silent?: number;
+  created_at: string;
+}
+
+export interface TaskRunLog {
+  task_id: string;
+  run_at: string;
+  duration_ms: number;
+  status: 'success' | 'error';
+  result: string | null;
+  error: string | null;
+}
+
+// --- Channel abstraction ---
+
+export interface Channel {
+  name: string;
+  connect(): Promise<void>;
+  sendMessage(jid: string, text: string): Promise<void>;
+  isConnected(): boolean;
+  ownsJid(jid: string): boolean;
+  disconnect(): Promise<void>;
+  // Optional: typing indicator. Channels that support it implement it.
+  setTyping?(jid: string, isTyping: boolean): Promise<void>;
+  // Optional: sync group/chat names from the platform.
+  syncGroups?(force: boolean): Promise<void>;
+  // Optional: list members of a channel/group for @mention support.
+  getChannelMembers?(jid: string): Promise<Array<{ id: string; name: string }>>;
+}
+
+// Callback type that channels use to deliver inbound messages
+export type OnInboundMessage = (chatJid: string, message: NewMessage) => void;
+
+// Callback for chat metadata discovery.
+// name is optional — channels that deliver names inline (Telegram) pass it here;
+// channels that sync names separately (via syncGroups) omit it.
+export type OnChatMetadata = (
+  chatJid: string,
+  timestamp: string,
+  name?: string,
+  channel?: string,
+  isGroup?: boolean,
+) => void;