@useatlas/create 0.0.1

package/templates/docker/src/lib/scheduler/delivery.ts

@@ -0,0 +1,248 @@
+/**
+ * Delivery dispatcher — routes scheduled task results to the configured channel.
+ *
+ * Switches on task.deliveryChannel and dispatches to the appropriate formatter
+ * and transport (email, Slack, webhook). Returns a delivery summary.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import type { ScheduledTask } from "@atlas/api/lib/scheduled-tasks";
+import type { AgentQueryResult } from "@atlas/api/lib/agent-query";
+import type { EmailRecipient, SlackRecipient, WebhookRecipient } from "@atlas/api/lib/scheduled-task-types";
+import { formatEmailReport } from "./format-email";
+import { formatSlackReport } from "./format-slack";
+import { formatWebhookPayload } from "./format-webhook";
+
+const log = createLogger("scheduler-delivery");
+
+export interface DeliverySummary {
+  attempted: number;
+  succeeded: number;
+  failed: number;
+}
+
+const EMPTY_SUMMARY: DeliverySummary = { attempted: 0, succeeded: 0, failed: 0 };
+
+/** RFC 5735 / RFC 4193 private and reserved IP ranges. */
+const BLOCKED_HOST_PATTERNS = [
+  /^localhost$/i,
+  /^127\./,
+  /^10\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^169\.254\./,
+  /^0\./,
+  /^\[::1\]$/,
+  /^\[fd/i,
+  /^\[fe80:/i,
+];
+
+const BLOCKED_HEADER_NAMES = new Set([
+  "authorization",
+  "cookie",
+  "host",
+  "x-forwarded-for",
+  "x-real-ip",
+]);
+
+/** Returns true if the URL targets a private/internal address. */
+function isBlockedUrl(urlString: string): boolean {
+  try {
+    const parsed = new URL(urlString);
+    // Block non-HTTPS in production
+    if (process.env.NODE_ENV === "production" && parsed.protocol !== "https:") {
+      return true;
+    }
+    const hostname = parsed.hostname;
+    return BLOCKED_HOST_PATTERNS.some((pattern) => pattern.test(hostname));
+  } catch {
+    return true; // Unparseable URLs are blocked
+  }
+}
+
+/** Filter out sensitive header names from user-supplied headers. */
+function sanitizeHeaders(headers: Record<string, string>): Record<string, string> {
+  const safe: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!BLOCKED_HEADER_NAMES.has(key.toLowerCase())) {
+      safe[key] = value;
+    } else {
+      log.warn({ header: key }, "Blocked sensitive header in webhook recipient");
+    }
+  }
+  return safe;
+}
+
+/**
+ * Deliver agent results to the task's configured channel and recipients.
+ * Returns a delivery summary with attempted/succeeded/failed counts.
+ */
+export async function deliverResult(
+  task: ScheduledTask,
+  result: AgentQueryResult,
+): Promise<DeliverySummary> {
+  if (task.recipients.length === 0) {
+    log.debug({ taskId: task.id }, "No recipients configured — skipping delivery");
+    return EMPTY_SUMMARY;
+  }
+
+  switch (task.deliveryChannel) {
+    case "email":
+      return deliverEmail(task, result);
+    case "slack":
+      return deliverSlack(task, result);
+    case "webhook":
+      return deliverWebhook(task, result);
+    default:
+      log.warn({ taskId: task.id, channel: task.deliveryChannel }, "Unknown delivery channel");
+      return EMPTY_SUMMARY;
+  }
+}
+
+async function deliverEmail(task: ScheduledTask, result: AgentQueryResult): Promise<DeliverySummary> {
+  const emailRecipients = task.recipients.filter(
+    (r): r is EmailRecipient => r.type === "email",
+  );
+  if (emailRecipients.length === 0) return EMPTY_SUMMARY;
+
+  const { subject, body } = formatEmailReport(task, result);
+
+  const resendKey = process.env.RESEND_API_KEY;
+  if (!resendKey) {
+    log.warn({ taskId: task.id, count: emailRecipients.length }, "RESEND_API_KEY not set — email delivery skipped");
+    return { attempted: emailRecipients.length, succeeded: 0, failed: emailRecipients.length };
+  }
+
+  const fromAddress = process.env.ATLAS_EMAIL_FROM ?? "Atlas <noreply@useatlas.dev>";
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const recipient of emailRecipients) {
+    try {
+      const resp = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${resendKey}`,
+        },
+        body: JSON.stringify({
+          from: fromAddress,
+          to: [recipient.address],
+          subject,
+          html: body,
+        }),
+      });
+
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        log.error({ taskId: task.id, recipient: recipient.address, status: resp.status, body: text.slice(0, 200) }, "Email delivery failed");
+        failed++;
+      } else {
+        log.info({ taskId: task.id, recipient: recipient.address }, "Email delivered");
+        succeeded++;
+      }
+    } catch (err) {
+      log.error({ taskId: task.id, recipient: recipient.address, err: err instanceof Error ? err.message : String(err) }, "Email delivery error");
+      failed++;
+    }
+  }
+
+  return { attempted: emailRecipients.length, succeeded, failed };
+}
+
+async function deliverSlack(task: ScheduledTask, result: AgentQueryResult): Promise<DeliverySummary> {
+  const slackRecipients = task.recipients.filter(
+    (r): r is SlackRecipient => r.type === "slack",
+  );
+  if (slackRecipients.length === 0) return EMPTY_SUMMARY;
+
+  const { text, blocks } = formatSlackReport(task, result);
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const recipient of slackRecipients) {
+    try {
+      let token: string | null = null;
+
+      if (recipient.teamId) {
+        const { getBotToken } = await import("@atlas/api/lib/slack/store");
+        token = await getBotToken(recipient.teamId);
+      }
+      if (!token) {
+        token = process.env.SLACK_BOT_TOKEN ?? null;
+      }
+
+      if (!token) {
+        log.warn({ taskId: task.id, channel: recipient.channel }, "No Slack bot token available — delivery skipped");
+        failed++;
+        continue;
+      }
+
+      const { postMessage } = await import("@atlas/api/lib/slack/api");
+      const resp = await postMessage(token, {
+        channel: recipient.channel,
+        text,
+        blocks,
+      });
+
+      if (!resp.ok) {
+        log.error({ taskId: task.id, channel: recipient.channel, error: resp.error }, "Slack delivery failed");
+        failed++;
+      } else {
+        log.info({ taskId: task.id, channel: recipient.channel }, "Slack message delivered");
+        succeeded++;
+      }
+    } catch (err) {
+      log.error({ taskId: task.id, channel: recipient.channel, err: err instanceof Error ? err.message : String(err) }, "Slack delivery error");
+      failed++;
+    }
+  }
+
+  return { attempted: slackRecipients.length, succeeded, failed };
+}
+
+async function deliverWebhook(task: ScheduledTask, result: AgentQueryResult): Promise<DeliverySummary> {
+  const webhookRecipients = task.recipients.filter(
+    (r): r is WebhookRecipient => r.type === "webhook",
+  );
+  if (webhookRecipients.length === 0) return EMPTY_SUMMARY;
+
+  const payload = formatWebhookPayload(task, result);
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const recipient of webhookRecipients) {
+    if (isBlockedUrl(recipient.url)) {
+      log.error({ taskId: task.id, url: recipient.url }, "Webhook URL blocked — targets private/internal address");
+      failed++;
+      continue;
+    }
+
+    const safeHeaders = sanitizeHeaders(recipient.headers ?? {});
+
+    try {
+      const resp = await fetch(recipient.url, {
+        method: "POST",
+        headers: {
+          ...safeHeaders,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        log.error({ taskId: task.id, url: recipient.url, status: resp.status, body: text.slice(0, 200) }, "Webhook delivery failed");
+        failed++;
+      } else {
+        log.info({ taskId: task.id, url: recipient.url }, "Webhook delivered");
+        succeeded++;
+      }
+    } catch (err) {
+      log.error({ taskId: task.id, url: recipient.url, err: err instanceof Error ? err.message : String(err) }, "Webhook delivery error");
+      failed++;
+    }
+  }
+
+  return { attempted: webhookRecipients.length, succeeded, failed };
+}

package/templates/docker/src/lib/scheduler/engine.ts

@@ -0,0 +1,317 @@
+/**
+ * Scheduler engine — tick-based loop that finds due tasks and executes them.
+ *
+ * Factory function returns a Scheduler object with start/stop lifecycle.
+ * Singleton via getScheduler() / _resetScheduler().
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import {
+  getTasksDueForExecution,
+  lockTaskForExecution,
+  createTaskRun,
+  completeTaskRun,
+  computeNextRun,
+  getScheduledTask,
+} from "@atlas/api/lib/scheduled-tasks";
+import { internalExecute } from "@atlas/api/lib/db/internal";
+import { executeScheduledTask } from "./executor";
+import { getConfig } from "@atlas/api/lib/config";
+
+const log = createLogger("scheduler");
+
+export interface Scheduler {
+  start(): void;
+  stop(): void;
+  isRunning(): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers (used by both createScheduler and runTick)
+// ---------------------------------------------------------------------------
+
+async function rescheduleTask(taskId: string) {
+  try {
+    const taskResult = await getScheduledTask(taskId);
+    if (taskResult.ok) {
+      const nextRun = computeNextRun(taskResult.data.cronExpression);
+      if (nextRun) {
+        internalExecute(
+          `UPDATE scheduled_tasks SET next_run_at = $1 WHERE id = $2`,
+          [nextRun.toISOString(), taskId],
+        );
+      }
+    }
+  } catch (err) {
+    log.error({ taskId, err: err instanceof Error ? err.message : String(err) }, "Failed to reschedule task");
+  }
+}
+
+function createScheduler(): Scheduler {
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let running = false;
+  let activeTasks = 0;
+
+  function getSchedulerConfig() {
+    const config = getConfig();
+    return {
+      maxConcurrentTasks: config?.scheduler?.maxConcurrentTasks ?? 5,
+      taskTimeout: config?.scheduler?.taskTimeout ?? 60_000,
+      tickIntervalSeconds: config?.scheduler?.tickIntervalSeconds ?? 60,
+    };
+  }
+
+  async function tick() {
+    const cfg = getSchedulerConfig();
+
+    if (activeTasks >= cfg.maxConcurrentTasks) {
+      log.debug({ activeTasks, max: cfg.maxConcurrentTasks }, "Scheduler tick skipped — at capacity");
+      return;
+    }
+
+    let dueTasks;
+    try {
+      dueTasks = await getTasksDueForExecution();
+    } catch (err) {
+      log.error({ err: err instanceof Error ? err.message : String(err) }, "Failed to fetch due tasks");
+      return;
+    }
+
+    if (dueTasks.length === 0) return;
+
+    log.info({ count: dueTasks.length }, "Scheduler tick — found due tasks");
+
+    const slotsAvailable = cfg.maxConcurrentTasks - activeTasks;
+    const tasksToRun = dueTasks.slice(0, slotsAvailable);
+
+    for (const task of tasksToRun) {
+      try {
+        const locked = await lockTaskForExecution(task.id);
+        if (!locked) {
+          log.debug({ taskId: task.id }, "Task already locked by another process");
+          continue;
+        }
+
+        activeTasks++;
+        executeAndDeliver(task.id, cfg.taskTimeout).finally(() => {
+          activeTasks--;
+        });
+      } catch (err) {
+        log.error({ taskId: task.id, err: err instanceof Error ? err.message : String(err) }, "Failed to lock/dispatch task");
+      }
+    }
+  }
+
+  async function executeAndDeliver(taskId: string, timeoutMs: number) {
+    const runId = await createTaskRun(taskId);
+    if (!runId) {
+      log.error({ taskId }, "Failed to create run record — attempting to reschedule");
+      await rescheduleTask(taskId);
+      return;
+    }
+
+    try {
+      const result = await executeScheduledTask(taskId, runId, timeoutMs);
+      completeTaskRun(runId, "success", { tokensUsed: result.tokensUsed });
+      log.info({ taskId, runId, tokensUsed: result.tokensUsed }, "Scheduled task completed successfully");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      completeTaskRun(runId, "failed", { error: message });
+      log.error({ taskId, runId, err: message }, "Scheduled task failed");
+    }
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+
+      const cfg = getSchedulerConfig();
+      log.info(
+        { intervalSeconds: cfg.tickIntervalSeconds, maxConcurrent: cfg.maxConcurrentTasks },
+        "Scheduler starting",
+      );
+
+      // First tick fires immediately
+      void tick().catch((err) => {
+        log.error({ err: err instanceof Error ? err.message : String(err) }, "Scheduler tick crashed");
+      });
+
+      timer = setInterval(() => {
+        void tick().catch((err) => {
+          log.error({ err: err instanceof Error ? err.message : String(err) }, "Scheduler tick crashed");
+        });
+      }, cfg.tickIntervalSeconds * 1000);
+      timer.unref();
+    },
+
+    stop() {
+      if (!running) return;
+      running = false;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      log.info("Scheduler stopped");
+    },
+
+    isRunning() {
+      return running;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+
+let _scheduler: Scheduler | null = null;
+
+export function getScheduler(): Scheduler {
+  if (!_scheduler) {
+    _scheduler = createScheduler();
+  }
+  return _scheduler;
+}
+
+/** Trigger a single task immediately (used by POST /:id/run route). */
+export async function triggerTask(taskId: string): Promise<void> {
+  const config = getConfig();
+  const timeoutMs = config?.scheduler?.taskTimeout ?? 60_000;
+
+  const locked = await lockTaskForExecution(taskId);
+  if (!locked) {
+    throw new Error("Failed to lock task for execution — task may be disabled or already running");
+  }
+
+  const runId = await createTaskRun(taskId);
+  if (!runId) {
+    throw new Error("Failed to create run record");
+  }
+
+  try {
+    const result = await executeScheduledTask(taskId, runId, timeoutMs);
+    completeTaskRun(runId, "success", { tokensUsed: result.tokensUsed });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    completeTaskRun(runId, "failed", { error: message });
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// runTick() — awaitable tick for serverless (Vercel Cron)
+// ---------------------------------------------------------------------------
+
+/**
+ * Summary of a single scheduler tick.
+ *
+ * Invariants:
+ * - All fields are non-negative integers.
+ * - tasksDispatched <= tasksFound (capped by maxConcurrentTasks, reduced by lock contention).
+ * - tasksCompleted + tasksFailed === tasksDispatched (every dispatched task settles).
+ */
+export interface TickResult {
+  tasksFound: number;
+  tasksDispatched: number;
+  tasksCompleted: number;
+  tasksFailed: number;
+  /** Non-null when the tick itself failed (e.g. DB unreachable). */
+  error?: string;
+}
+
+/**
+ * Run a single scheduler tick that **awaits** all task executions.
+ *
+ * Unlike the in-process `tick()` (fire-and-forget inside `setInterval`),
+ * this function returns only after every dispatched task has settled —
+ * required for serverless environments where the function cannot exit early.
+ *
+ * When the due-task query fails, the error is surfaced in `result.error`
+ * so the caller can return an appropriate HTTP status (not a silent 200).
+ */
+export async function runTick(): Promise<TickResult> {
+  const config = getConfig();
+  const maxConcurrent = config?.scheduler?.maxConcurrentTasks ?? 5;
+  const taskTimeout = config?.scheduler?.taskTimeout ?? 60_000;
+
+  let dueTasks;
+  try {
+    dueTasks = await getTasksDueForExecution();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err: message }, "runTick: failed to fetch due tasks");
+    return { tasksFound: 0, tasksDispatched: 0, tasksCompleted: 0, tasksFailed: 0, error: message };
+  }
+
+  if (dueTasks.length === 0) {
+    return { tasksFound: 0, tasksDispatched: 0, tasksCompleted: 0, tasksFailed: 0 };
+  }
+
+  const tasksToRun = dueTasks.slice(0, maxConcurrent);
+  type TaskOutcome = "completed" | "failed";
+  const promises: Promise<TaskOutcome>[] = [];
+
+  let tasksDispatched = 0;
+
+  for (const task of tasksToRun) {
+    let locked: boolean;
+    try {
+      locked = await lockTaskForExecution(task.id);
+    } catch (err) {
+      log.error({ taskId: task.id, err: err instanceof Error ? err.message : String(err) }, "runTick: lock error");
+      continue;
+    }
+    if (!locked) {
+      log.debug({ taskId: task.id }, "runTick: task already locked");
+      continue;
+    }
+
+    tasksDispatched++;
+
+    promises.push(
+      (async (): Promise<TaskOutcome> => {
+        const runId = await createTaskRun(task.id);
+        if (!runId) {
+          log.error({ taskId: task.id }, "runTick: failed to create run record — rescheduling");
+          await rescheduleTask(task.id);
+          return "failed";
+        }
+        try {
+          const execResult = await executeScheduledTask(task.id, runId, taskTimeout);
+          completeTaskRun(runId, "success", { tokensUsed: execResult.tokensUsed });
+          log.info({ taskId: task.id, runId }, "runTick: task completed");
+          return "completed";
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          completeTaskRun(runId, "failed", { error: message });
+          log.error({ taskId: task.id, runId, err: message }, "runTick: task failed");
+          return "failed";
+        }
+      })(),
+    );
+  }
+
+  const outcomes = await Promise.allSettled(promises);
+  let tasksCompleted = 0;
+  let tasksFailed = 0;
+  for (const o of outcomes) {
+    if (o.status === "fulfilled" && o.value === "completed") tasksCompleted++;
+    else tasksFailed++;
+  }
+
+  return {
+    tasksFound: dueTasks.length,
+    tasksDispatched,
+    tasksCompleted,
+    tasksFailed,
+  };
+}
+
+/** Reset singleton for testing. */
+export function _resetScheduler(): void {
+  if (_scheduler) {
+    _scheduler.stop();
+    _scheduler = null;
+  }
+}

package/templates/docker/src/lib/scheduler/executor.ts

@@ -0,0 +1,73 @@
+/**
+ * Scheduled task executor — bridges the scheduler to executeAgentQuery().
+ *
+ * Fetches the task, runs the agent, delivers results, and returns execution
+ * metadata. The executor does NOT update the run record — callers (engine.ts)
+ * own run completion to avoid double-writes.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import { getScheduledTask } from "@atlas/api/lib/scheduled-tasks";
+import { executeAgentQuery } from "@atlas/api/lib/agent-query";
+import { deliverResult } from "./delivery";
+
+const log = createLogger("scheduler-executor");
+
+export interface ExecutionResult {
+  tokensUsed: number;
+  deliveryAttempted: number;
+  deliverySucceeded: number;
+  deliveryFailed: number;
+}
+
+/**
+ * Execute a scheduled task: run the agent query and deliver results.
+ * Returns execution metadata on success. Throws on failure.
+ * Callers are responsible for updating the run record.
+ */
+export async function executeScheduledTask(
+  taskId: string,
+  runId: string,
+  timeoutMs: number,
+): Promise<ExecutionResult> {
+  const taskResult = await getScheduledTask(taskId);
+  if (!taskResult.ok) {
+    throw new Error(`Task not found: ${taskId}`);
+  }
+
+  const task = taskResult.data;
+  const requestId = `sched-${taskId}-${runId}`;
+
+  log.info({ taskId, runId, question: task.question.slice(0, 100) }, "Executing scheduled task");
+
+  // Run agent with timeout — clear timer to avoid resource leak
+  let timer: ReturnType<typeof setTimeout>;
+  const agentPromise = executeAgentQuery(task.question, requestId);
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`Task execution timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+
+  let agentResult;
+  try {
+    agentResult = await Promise.race([agentPromise, timeoutPromise]);
+  } finally {
+    clearTimeout(timer!);
+  }
+
+  // Deliver results to configured channels (best-effort)
+  const delivery = await deliverResult(task, agentResult);
+
+  if (delivery.failed > 0) {
+    log.warn(
+      { taskId, runId, ...delivery },
+      "Partial delivery failure — some recipients did not receive results",
+    );
+  }
+
+  return {
+    tokensUsed: agentResult.usage.totalTokens,
+    deliveryAttempted: delivery.attempted,
+    deliverySucceeded: delivery.succeeded,
+    deliveryFailed: delivery.failed,
+  };
+}