@rozek/nanoclaw 0.0.1

package/src/task-scheduler.ts

@@ -0,0 +1,328 @@
+import { ChildProcess } from 'child_process';
+import { CronExpressionParser } from 'cron-parser';
+import fs from 'fs';
+
+import { ASSISTANT_NAME, SCHEDULER_POLL_INTERVAL, 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';
+
+// Web-channel JID prefix and dedicated cron session JID.
+// Scheduled task output for web sessions is always routed to the cron session
+// so users see it in one dedicated place instead of the originating session.
+const WEB_JID_PREFIX = 'local@web-';
+const WEB_JID_LEGACY = 'local@web'; // Legacy JID used before per-session JIDs were introduced
+const CRON_SESSION_JID = 'local@web-cron';
+
+/**
+ * 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 });
+
+  logger.info(
+    { taskId: task.id, group: task.group_folder },
+    'Running scheduled task',
+  );
+
+  const groups = deps.registeredGroups();
+  let group = Object.values(groups).find((g) => g.folder === task.group_folder);
+
+  if (!group) {
+    // Fall back to the first isMain group so that legacy tasks created with
+    // group_folder='main' still run after a web-channel migration.
+    const fallback = Object.values(groups).find((g) => g.isMain === true);
+    if (fallback) {
+      logger.warn(
+        {
+          taskId: task.id,
+          groupFolder: task.group_folder,
+          fallback: fallback.folder,
+        },
+        'Group not found for task, falling back to main group',
+      );
+      group = fallback;
+    } else {
+      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(
+    group.folder,
+    isMain,
+    tasks.map((t) => ({
+      id: t.id,
+      groupFolder: t.group_folder,
+      prompt: t.prompt,
+      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 web sessions, display output in the dedicated cron session instead of
+  // the originating session, so all scheduled-task output is in one place.
+  // Also handle legacy JID 'local@web' (without suffix) used before per-session JIDs.
+  const displayJid =
+    task.chat_jid === WEB_JID_LEGACY || task.chat_jid.startsWith(WEB_JID_PREFIX)
+      ? CRON_SESSION_JID
+      : task.chat_jid;
+
+  // For group context mode, look up the session by chatJid first (per-session key),
+  // then fall back to group_folder (backward compatibility).
+  const sessions = deps.getSessions();
+  const sessionId =
+    task.context_mode === 'group'
+      ? (sessions[task.chat_jid] ?? sessions[task.group_folder])
+      : undefined;
+
+  // Each task gets its own queue JID so it runs in parallel with user messages
+  // and with other tasks, without blocking the user's message queue slot.
+  const taskQueueJid = `task:${task.id}`;
+
+  // Send a header to the cron session so the user knows which task is running.
+  const promptPreview = task.prompt.split('\n')[0].slice(0, 80);
+  const scheduleLabel =
+    task.schedule_type === 'interval'
+      ? `every ${Math.round(parseInt(task.schedule_value, 10) / 60000)} min`
+      : task.schedule_value;
+  const taskHeader = `---\n**Task #${task.id}** | ${scheduleLabel}\n> ${promptPreview}`;
+  await deps.sendMessage(displayJid, taskHeader);
+
+  // 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.
+  const TASK_CLOSE_DELAY_MS = 10000;
+  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(taskQueueJid);
+    }, TASK_CLOSE_DELAY_MS);
+  };
+
+  try {
+    const output = await runContainerAgent(
+      group,
+      {
+        prompt: task.prompt,
+        sessionId,
+        groupFolder: group.folder,
+        chatJid: task.chat_jid,
+        isMain,
+        isScheduledTask: true,
+        assistantName: ASSISTANT_NAME,
+      },
+      (proc, containerName) =>
+        deps.onProcess(taskQueueJid, proc, containerName, group.folder),
+      async (streamedOutput: ContainerOutput) => {
+        if (streamedOutput.result) {
+          result = streamedOutput.result;
+          // Forward result to the display JID (cron session for web tasks)
+          await deps.sendMessage(displayJid, streamedOutput.result);
+          scheduleClose();
+        }
+        if (streamedOutput.status === 'success') {
+          deps.queue.notifyIdle(taskQueueJid);
+          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 nextRun = computeNextRun(task);
+  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;
+        }
+
+        // Use a task-specific queue JID so the task runs in parallel with
+        // user messages and other tasks (not serialized on the group's slot).
+        deps.queue.enqueueTask(`task:${currentTask.id}`, 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/src/timezone.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+
+import { formatLocalTime } 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');
+  });
+});

package/src/timezone.ts

@@ -0,0 +1,16 @@
+/**
+ * Convert a UTC ISO timestamp to a localized display string.
+ * Uses the Intl API (no external dependencies).
+ */
+export function formatLocalTime(utcIso: string, timezone: string): string {
+  const date = new Date(utcIso);
+  return date.toLocaleString('en-US', {
+    timeZone: timezone,
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  });
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+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
+}
+
+/**
+ * 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)
+}
+
+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;
+  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;
+  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';
+  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: live tool-use status. Call with null to clear the status display.
+  setStatus?(jid: string, tool: string | null, inputSnippet?: string): void;
+}
+
+// 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;

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts', 'setup/**/*.test.ts'],
+  },
+});

package/vitest.skills.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['.claude/skills/**/tests/*.test.ts'],
+  },
+});