@useatlas/create 0.0.5 → 0.0.7

package/templates/docker/src/api/routes/scheduled-tasks.ts

@@ -2,18 +2,19 @@
  * Scheduled tasks REST routes — CRUD + trigger + run history.
  *
  * Gated behind ATLAS_SCHEDULER_ENABLED=true (conditional mount in index.ts).
- * Follows the same auth → rate limit → withRequestContext pattern as conversations.ts.
+ * CRUD routes use `adminAuth` + `requireOrgContext` middleware (admin/owner
+ * role required, org-scoped). The `/tick` endpoint uses its own cron-secret
+ * auth and is registered on the outer app so it bypasses user-auth middleware.
  */
 
-import { Hono } from "hono";
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { Effect } from "effect";
+import { runEffect } from "@atlas/api/lib/effect/hono";
+import { RequestContext, AuthContext } from "@atlas/api/lib/effect/services";
+import { validationHook } from "./validation-hook";
+import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
-import { createLogger, withRequestContext } from "@atlas/api/lib/logger";
-import type { AuthResult } from "@atlas/api/lib/auth/types";
-import {
-  authenticateRequest,
-  checkRateLimit,
-  getClientIP,
-} from "@atlas/api/lib/auth/middleware";
+import { createLogger } from "@atlas/api/lib/logger";
 import { hasInternalDB } from "@atlas/api/lib/db/internal";
 import {
   createScheduledTask,
@@ -22,11 +23,15 @@ import {
   updateScheduledTask,
   deleteScheduledTask,
   listTaskRuns,
+  listAllRuns,
   validateCronExpression,
   type CrudFailReason,
 } from "@atlas/api/lib/scheduled-tasks";
-import { DELIVERY_CHANNELS } from "@atlas/api/lib/scheduled-task-types";
+import { DELIVERY_CHANNELS, RUN_STATUSES, type RunStatus } from "@atlas/api/lib/scheduled-task-types";
 import { ACTION_APPROVAL_MODES } from "@atlas/api/lib/action-types";
+import { type AuthEnv } from "./middleware";
+import { ErrorSchema, parsePagination } from "./shared-schemas";
+import { createAdminRouter, requireOrgContext } from "./admin-router";
 
 const log = createLogger("scheduled-tasks-routes");
 
@@ -40,7 +45,7 @@ const RecipientSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("webhook"), url: z.string().url(), headers: z.record(z.string(), z.string()).optional() }),
 ]);
 
-export const CreateScheduledTaskSchema = z.object({
+const CreateScheduledTaskSchema = z.object({
   name: z.string().min(1).max(200),
   question: z.string().min(1).max(2000),
   cronExpression: z.string().min(1),
@@ -50,7 +55,7 @@ export const CreateScheduledTaskSchema = z.object({
   approvalMode: z.enum(ACTION_APPROVAL_MODES).default("auto"),
 });
 
-export const UpdateScheduledTaskSchema = z.object({
+const UpdateScheduledTaskSchema = z.object({
   name: z.string().min(1).max(200).optional(),
   question: z.string().min(1).max(2000).optional(),
   cronExpression: z.string().min(1).optional(),
@@ -63,405 +68,496 @@ export const UpdateScheduledTaskSchema = z.object({
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-function crudFailResponse(reason: CrudFailReason) {
+
+function crudFailResponse(reason: CrudFailReason, requestId?: string) {
   switch (reason) {
     case "no_db":
       return { body: { error: "not_available", message: "Scheduled tasks require an internal database." }, status: 404 as const };
     case "not_found":
       return { body: { error: "not_found", message: "Scheduled task not found." }, status: 404 as const };
     case "error":
-      return { body: { error: "internal_error", message: "A database error occurred. Please try again." }, status: 500 as const };
+      return { body: { error: "internal_error", message: "A database error occurred. Please try again.", ...(requestId && { requestId }) }, status: 500 as const };
     default: {
       const _exhaustive: never = reason;
-      return { body: { error: "internal_error", message: `Unexpected failure: ${_exhaustive}` }, status: 500 as const };
+      return { body: { error: "internal_error", message: `Unexpected failure: ${_exhaustive}`, ...(requestId && { requestId }) }, status: 500 as const };
     }
   }
 }
 
-const scheduledTasks = new Hono();
-
 // ---------------------------------------------------------------------------
-// Shared auth preamble
+// Route definitions
 // ---------------------------------------------------------------------------
 
-async function authPreamble(req: Request, requestId: string) {
-  let authResult: AuthResult;
-  try {
-    authResult = await authenticateRequest(req);
-  } catch (err) {
-    log.error(
-      { err: err instanceof Error ? err : new Error(String(err)), requestId },
-      "Auth dispatch failed",
-    );
-    return { error: { error: "auth_error", message: "Authentication system error" }, status: 500 as const };
-  }
-  if (!authResult.authenticated) {
-    log.warn({ requestId, status: authResult.status }, "Authentication failed");
-    return { error: { error: "auth_error", message: authResult.error }, status: authResult.status as 401 | 403 | 500 };
-  }
+const listTasksRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Scheduled Tasks"],
+  summary: "List scheduled tasks",
+  description:
+    "Returns scheduled tasks for the active organization. Requires admin role, ATLAS_SCHEDULER_ENABLED=true, and an internal database.",
+  request: {
+    query: z.object({
+      limit: z.string().optional().openapi({
+        param: { name: "limit", in: "query" },
+        description: "Maximum number of items to return (1-100, default 20).",
+      }),
+      offset: z.string().optional().openapi({
+        param: { name: "offset", in: "query" },
+        description: "Number of items to skip (default 0).",
+      }),
+      enabled: z.string().optional().openapi({
+        param: { name: "enabled", in: "query" },
+        description: "Filter by enabled status.",
+      }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "Paginated list of scheduled tasks",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    404: { description: "Scheduled tasks not available", content: { "application/json": { schema: ErrorSchema } } },
+    429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } },
+  },
+});
 
-  const ip = getClientIP(req);
-  const rateLimitKey = authResult.user?.id ?? (ip ? `ip:${ip}` : "anon");
-  const rateCheck = checkRateLimit(rateLimitKey);
-  if (!rateCheck.allowed) {
-    const retryAfterSeconds = Math.ceil((rateCheck.retryAfterMs ?? 60000) / 1000);
-    return {
-      error: { error: "rate_limited", message: "Too many requests. Please wait before trying again.", retryAfterSeconds },
-      status: 429 as const,
-      headers: { "Retry-After": String(retryAfterSeconds) },
-    };
-  }
+const createTaskRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Scheduled Tasks"],
+  summary: "Create a scheduled task",
+  description: "Creates a recurring query task with a cron schedule and delivery channel. Requires admin role.",
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateScheduledTaskSchema } },
+      required: true,
+    },
+  },
+  responses: {
+    201: { description: "Scheduled task created", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    400: { description: "Invalid request body or cron expression", content: { "application/json": { schema: ErrorSchema } } },
+    401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    404: { description: "Feature not available", content: { "application/json": { schema: ErrorSchema } } },
+    422: { description: "Validation error", content: { "application/json": { schema: ErrorSchema.extend({ details: z.array(z.unknown()).optional() }) } } },
+    429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } },
+  },
+});
 
-  return { authResult };
-}
+const tickRoute = createRoute({
+  method: "post",
+  path: "/tick",
+  tags: ["Scheduled Tasks"],
+  summary: "Trigger scheduler tick",
+  description:
+    "Serverless scheduler tick endpoint for Vercel Cron or external cron services. " +
+    "Checks for due tasks and executes them. Requires CRON_SECRET or ATLAS_SCHEDULER_SECRET.",
+  responses: {
+    200: { description: "Tick completed", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    401: { description: "Invalid or missing cron secret", content: { "application/json": { schema: ErrorSchema } } },
+    404: { description: "Feature not available (no internal database configured)", content: { "application/json": { schema: ErrorSchema } } },
+    500: { description: "Tick execution failed", content: { "application/json": { schema: ErrorSchema } } },
+  },
+});
+
+const listAllRunsRoute = createRoute({
+  method: "get",
+  path: "/runs",
+  tags: ["Scheduled Tasks"],
+  summary: "List all task runs",
+  description: "Returns cross-task run history with filtering by task, status, and date range. Requires admin role.",
+  request: {
+    query: z.object({
+      limit: z.string().optional().openapi({ param: { name: "limit", in: "query" }, description: "Maximum number of runs (1-100, default 20)." }),
+      offset: z.string().optional().openapi({ param: { name: "offset", in: "query" }, description: "Number of items to skip (default 0)." }),
+      task_id: z.string().optional().openapi({ param: { name: "task_id", in: "query" }, description: "Filter by task ID." }),
+      status: z.string().optional().openapi({ param: { name: "status", in: "query" }, description: "Filter by run status." }),
+      date_from: z.string().optional().openapi({ param: { name: "date_from", in: "query" }, description: "Filter from date (YYYY-MM-DD)." }),
+      date_to: z.string().optional().openapi({ param: { name: "date_to", in: "query" }, description: "Filter to date (YYYY-MM-DD)." }),
+    }),
+  },
+  responses: {
+    200: { description: "List of task runs", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    404: { description: "Not available", content: { "application/json": { schema: ErrorSchema } } },
+    429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } },
+    500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } },
+  },
+});
+
+const getTaskRoute = createRoute({ method: "get", path: "/{id}", tags: ["Scheduled Tasks"], summary: "Get scheduled task", description: "Returns a scheduled task with its 10 most recent runs. Requires admin role.", request: { params: z.object({ id: z.string().openapi({ param: { name: "id", in: "path" }, example: "00000000-0000-0000-0000-000000000000" }) }) }, responses: { 200: { description: "Scheduled task with recent runs", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 400: { description: "Invalid task ID format", content: { "application/json": { schema: ErrorSchema } } }, 401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 404: { description: "Task not found", content: { "application/json": { schema: ErrorSchema } } }, 429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } } } });
+
+const updateTaskRoute = createRoute({ method: "put", path: "/{id}", tags: ["Scheduled Tasks"], summary: "Update a scheduled task", description: "Updates a scheduled task. All fields are optional. Requires admin role.", request: { params: z.object({ id: z.string().openapi({ param: { name: "id", in: "path" }, example: "00000000-0000-0000-0000-000000000000" }) }), body: { content: { "application/json": { schema: UpdateScheduledTaskSchema } }, required: true } }, responses: { 200: { description: "Updated scheduled task", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 400: { description: "Invalid request body or cron expression", content: { "application/json": { schema: ErrorSchema } } }, 401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 404: { description: "Task not found", content: { "application/json": { schema: ErrorSchema } } }, 422: { description: "Validation error", content: { "application/json": { schema: ErrorSchema.extend({ details: z.array(z.unknown()).optional() }) } } }, 429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } } } });
+
+const deleteTaskRoute = createRoute({ method: "delete", path: "/{id}", tags: ["Scheduled Tasks"], summary: "Delete a scheduled task", description: "Soft-deletes (disables) a scheduled task. Requires admin role.", request: { params: z.object({ id: z.string().openapi({ param: { name: "id", in: "path" }, example: "00000000-0000-0000-0000-000000000000" }) }) }, responses: { 204: { description: "Task deleted successfully" }, 400: { description: "Invalid task ID format", content: { "application/json": { schema: ErrorSchema } } }, 401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 404: { description: "Task not found", content: { "application/json": { schema: ErrorSchema } } }, 429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } } } });
+
+const triggerTaskRoute = createRoute({ method: "post", path: "/{id}/run", tags: ["Scheduled Tasks"], summary: "Trigger immediate execution", description: "Triggers an immediate execution of a scheduled task. Requires admin role.", request: { params: z.object({ id: z.string().openapi({ param: { name: "id", in: "path" }, example: "00000000-0000-0000-0000-000000000000" }) }) }, responses: { 200: { description: "Task triggered", content: { "application/json": { schema: z.object({ message: z.string(), taskId: z.string() }) } } }, 400: { description: "Invalid task ID format", content: { "application/json": { schema: ErrorSchema } } }, 401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 404: { description: "Task not found", content: { "application/json": { schema: ErrorSchema } } }, 429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } } } });
+
+const previewTaskRoute = createRoute({ method: "post", path: "/{id}/preview", tags: ["Scheduled Tasks"], summary: "Preview delivery format", description: "Dry-run delivery format with mock data. Requires admin role.", request: { params: z.object({ id: z.string().openapi({ param: { name: "id", in: "path" }, example: "00000000-0000-0000-0000-000000000000" }) }) }, responses: { 200: { description: "Delivery preview", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 400: { description: "Invalid task ID format", content: { "application/json": { schema: ErrorSchema } } }, 401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 404: { description: "Task not found", content: { "application/json": { schema: ErrorSchema } } }, 429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } } } });
+
+const listTaskRunsRoute = createRoute({ method: "get", path: "/{id}/runs", tags: ["Scheduled Tasks"], summary: "List task runs", description: "Returns past execution runs for a scheduled task. Requires admin role.", request: { params: z.object({ id: z.string().openapi({ param: { name: "id", in: "path" }, example: "00000000-0000-0000-0000-000000000000" }) }), query: z.object({ limit: z.string().optional().openapi({ param: { name: "limit", in: "query" }, description: "Maximum number of runs to return (1-100, default 20)." }) }) }, responses: { 200: { description: "List of task runs", content: { "application/json": { schema: z.object({ runs: z.array(z.record(z.string(), z.unknown())) }) } } }, 400: { description: "Invalid task ID format", content: { "application/json": { schema: ErrorSchema } } }, 401: { description: "Authentication required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 403: { description: "Forbidden — admin role required", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 404: { description: "Task not found", content: { "application/json": { schema: ErrorSchema } } }, 429: { description: "Rate limit exceeded", content: { "application/json": { schema: z.record(z.string(), z.unknown()) } } }, 500: { description: "Internal server error", content: { "application/json": { schema: ErrorSchema } } } } });
 
 // ---------------------------------------------------------------------------
-// GET / — list scheduled tasks
+// Router
 // ---------------------------------------------------------------------------
 
-scheduledTasks.get("/", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
+// Outer app: tick route (cron-secret auth, no user-auth middleware)
+const scheduledTasks = new OpenAPIHono<AuthEnv>({ defaultHook: validationHook });
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
+// Inner app: admin-authenticated, org-scoped routes (adminAuth + requireOrgContext)
+const authed = createAdminRouter();
+authed.use(requireOrgContext());
 
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
+// Tick also needs a JSON-parse error handler (outer app only — authed uses eeOnError via createAdminRouter)
+scheduledTasks.onError((err, c) => {
+  if (err instanceof HTTPException) {
+    if (err.res) return err.res;
+    if (err.status === 400) {
+      return c.json({ error: "invalid_request", message: "Invalid JSON body." }, 400);
+    }
   }
-  const { authResult } = preamble;
+  throw err;
+});
+
+// ---------------------------------------------------------------------------
+// GET / — list scheduled tasks
+// ---------------------------------------------------------------------------
+
+authed.openapi(listTasksRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
 
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    const rawLimit = parseInt(c.req.query("limit") ?? "20", 10);
-    const rawOffset = parseInt(c.req.query("offset") ?? "0", 10);
-    const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, 100) : 20;
-    const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? rawOffset : 0;
+    const { limit, offset } = parsePagination(c, { limit: 20, maxLimit: 100 });
     const enabledParam = c.req.query("enabled");
     const enabled = enabledParam === "true" ? true : enabledParam === "false" ? false : undefined;
 
-    const result = await listScheduledTasks({
-      ownerId: authResult.user?.id,
+    const items = yield* Effect.promise(() => listScheduledTasks({
+      orgId,
       enabled,
       limit,
       offset,
-    });
-    return c.json(result);
-  });
+    }));
+    return c.json(items, 200);
+  }), { label: "list scheduled tasks" });
 });
 
 // ---------------------------------------------------------------------------
 // POST / — create scheduled task
 // ---------------------------------------------------------------------------
 
-scheduledTasks.post("/", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
+authed.openapi(
+  createTaskRoute,
+  async (c) => {
+    return runEffect(c, Effect.gen(function* () {
+      const { requestId } = yield* RequestContext;
+      const { orgId, user } = yield* AuthContext;
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
+      const parsed = c.req.valid("json");
 
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
-  }
-  const { authResult } = preamble;
-
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    let body: unknown;
-    try {
-      body = await req.json();
-    } catch {
-      return c.json({ error: "invalid_request", message: "Invalid JSON body." }, 400);
-    }
-
-    const parsed = CreateScheduledTaskSchema.safeParse(body);
-    if (!parsed.success) {
-      const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-      return c.json({ error: "invalid_request", message: issues }, 400);
-    }
+      // Validate cron expression
+      const cronCheck = validateCronExpression(parsed.cronExpression);
+      if (!cronCheck.valid) {
+        return c.json({ error: "invalid_request", message: `Invalid cron expression: ${cronCheck.error}` }, 400);
+      }
 
-    // Validate cron expression
-    const cronCheck = validateCronExpression(parsed.data.cronExpression);
-    if (!cronCheck.valid) {
-      return c.json({ error: "invalid_request", message: `Invalid cron expression: ${cronCheck.error}` }, 400);
-    }
+      const createResult = yield* Effect.promise(() => createScheduledTask({
+        ownerId: user?.id ?? "anonymous",
+        orgId,
+        name: parsed.name,
+        question: parsed.question,
+        cronExpression: parsed.cronExpression,
+        deliveryChannel: parsed.deliveryChannel,
+        recipients: parsed.recipients,
+        connectionId: parsed.connectionId ?? null,
+        approvalMode: parsed.approvalMode,
+      }));
+
+      if (!createResult.ok) {
+        const fail = crudFailResponse(createResult.reason, requestId);
+        return c.json(fail.body, fail.status);
+      }
 
-    const result = await createScheduledTask({
-      ownerId: authResult.user?.id ?? "anonymous",
-      name: parsed.data.name,
-      question: parsed.data.question,
-      cronExpression: parsed.data.cronExpression,
-      deliveryChannel: parsed.data.deliveryChannel,
-      recipients: parsed.data.recipients,
-      connectionId: parsed.data.connectionId ?? null,
-      approvalMode: parsed.data.approvalMode,
-    });
-
-    if (!result.ok) {
-      const fail = crudFailResponse(result.reason);
-      return c.json(fail.body, fail.status);
+      return c.json(createResult.data, 201);
+    }), { label: "create scheduled task" });
+  },
+  (result, c) => {
+    if (!result.success) {
+      return c.json(
+        { error: "validation_error", message: "Invalid request body.", details: result.error.issues },
+        422,
+      );
     }
-
-    return c.json(result.data, 201);
-  });
-});
+  },
+);
 
 // ---------------------------------------------------------------------------
 // POST /tick — serverless scheduler tick (Vercel Cron)
 // ---------------------------------------------------------------------------
 
-scheduledTasks.post("/tick", async (c) => {
-  const req = c.req.raw;
+scheduledTasks.openapi(tickRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const req = c.req.raw;
+    const requestId = crypto.randomUUID();
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
+    if (!hasInternalDB()) {
+      return c.json({ error: "not_available", message: "Scheduled tasks require an internal database.", requestId }, 404);
+    }
 
-  // Auth: check CRON_SECRET (Vercel-native) or ATLAS_SCHEDULER_SECRET (generic)
-  const secret = process.env.CRON_SECRET ?? process.env.ATLAS_SCHEDULER_SECRET;
-  const { getConfig } = await import("@atlas/api/lib/config");
-  const config = getConfig();
+    // Auth: check CRON_SECRET (Vercel-native) or ATLAS_SCHEDULER_SECRET (generic)
+    const secret = process.env.CRON_SECRET ?? process.env.ATLAS_SCHEDULER_SECRET;
+    const { getConfig } = yield* Effect.promise(() => import("@atlas/api/lib/config"));
+    const config = getConfig();
 
-  if (secret) {
-    const authHeader = req.headers.get("authorization");
-    if (authHeader !== `Bearer ${secret}`) {
-      return c.json({ error: "unauthorized", message: "Invalid or missing cron secret." }, 401);
+    if (secret) {
+      const authHeader = req.headers.get("authorization");
+      if (authHeader !== `Bearer ${secret}`) {
+        return c.json({ error: "unauthorized", message: "Invalid or missing cron secret.", requestId }, 401);
+      }
+    } else if (config?.scheduler?.backend === "vercel") {
+      return c.json(
+        { error: "misconfigured", message: "Vercel backend requires CRON_SECRET or ATLAS_SCHEDULER_SECRET to be set.", requestId },
+        500,
+      );
+    } else if (process.env.NODE_ENV === "production") {
+      return c.json(
+        { error: "misconfigured", message: "CRON_SECRET or ATLAS_SCHEDULER_SECRET must be set in production.", requestId },
+        500,
+      );
+    } else {
+      log.warn("POST /tick called without secret — allowing because NODE_ENV is not 'production'");
     }
-  } else if (config?.scheduler?.backend === "vercel") {
-    return c.json(
-      { error: "misconfigured", message: "Vercel backend requires CRON_SECRET or ATLAS_SCHEDULER_SECRET to be set." },
-      500,
-    );
-  } else if (process.env.NODE_ENV === "production") {
-    return c.json(
-      { error: "misconfigured", message: "CRON_SECRET or ATLAS_SCHEDULER_SECRET must be set in production." },
-      500,
-    );
-  } else {
-    log.warn("POST /tick called without secret — allowing because NODE_ENV is not 'production'");
-  }
 
-  try {
-    const { runTick } = await import("@atlas/api/lib/scheduler/engine");
-    const result = await runTick();
-    if (result.error) {
-      return c.json(result, 500);
+    const tickOutcome = yield* Effect.tryPromise({
+      try: async () => {
+        const { runTick } = await import("@atlas/api/lib/scheduler/engine");
+        return runTick();
+      },
+      catch: (err) => err instanceof Error ? err : new Error(String(err)),
+    }).pipe(Effect.catchAll((err) => {
+      log.error({ err, requestId }, "Tick execution failed");
+      return Effect.succeed({ error: "internal_error" as const, requestId });
+    }));
+
+    if ("error" in tickOutcome && tickOutcome.error === "internal_error") {
+      return c.json({ error: "internal_error", message: "Tick execution failed.", requestId }, 500);
     }
-    return c.json(result);
-  } catch (err) {
-    log.error({ err: err instanceof Error ? err : new Error(String(err)) }, "Tick execution failed");
-    return c.json({ error: "internal_error", message: "Tick execution failed." }, 500);
-  }
+    if (tickOutcome.error) {
+      return c.json({ error: "tick_failed", message: tickOutcome.error, requestId }, 500);
+    }
+    return c.json(tickOutcome, 200);
+  }), { label: "scheduler tick" });
 });
 
 // ---------------------------------------------------------------------------
-// GET /:id — get scheduled task with recent runs
+// GET /runs — cross-task run history
 // ---------------------------------------------------------------------------
 
-scheduledTasks.get("/:id", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
+authed.openapi(listAllRunsRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    const { limit, offset } = parsePagination(c, { limit: 20, maxLimit: 100 });
+
+    const taskIdParam = c.req.query("task_id") || undefined;
+    const taskId = taskIdParam && UUID_RE.test(taskIdParam) ? taskIdParam : undefined;
+    const statusParam = c.req.query("status");
+    const status = statusParam && (RUN_STATUSES as readonly string[]).includes(statusParam)
+      ? (statusParam as RunStatus)
+      : undefined;
+    const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+    const dateFromParam = c.req.query("date_from") || undefined;
+    const dateToParam = c.req.query("date_to") || undefined;
+    const dateFrom = dateFromParam && ISO_DATE_RE.test(dateFromParam) ? dateFromParam : undefined;
+    const dateTo = dateToParam && ISO_DATE_RE.test(dateToParam) ? dateToParam : undefined;
+
+    const runs = yield* Effect.promise(() => listAllRuns({ orgId, taskId, status, dateFrom, dateTo, limit, offset }));
+    return c.json(runs, 200);
+  }), { label: "list all runs" });
+});
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
+// ---------------------------------------------------------------------------
+// GET /:id — get scheduled task with recent runs
+// ---------------------------------------------------------------------------
 
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
-  }
-  const { authResult } = preamble;
+authed.openapi(getTaskRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { orgId } = yield* AuthContext;
 
-  const id = c.req.param("id");
-  if (!UUID_RE.test(id)) {
-    return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
-  }
+    const { id } = c.req.valid("param");
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
+    }
 
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    const result = await getScheduledTask(id, authResult.user?.id);
-    if (!result.ok) {
-      const fail = crudFailResponse(result.reason);
+    const taskResult = yield* Effect.promise(() => getScheduledTask(id, { orgId }));
+    if (!taskResult.ok) {
+      const fail = crudFailResponse(taskResult.reason, requestId);
       return c.json(fail.body, fail.status);
     }
 
-    const runs = await listTaskRuns(id, { limit: 10 });
-    return c.json({ ...result.data, recentRuns: runs });
-  });
+    const runs = yield* Effect.promise(() => listTaskRuns(id, { limit: 10 }));
+    return c.json({ ...taskResult.data, recentRuns: runs }, 200);
+  }), { label: "get scheduled task" });
 });
 
 // ---------------------------------------------------------------------------
 // PUT /:id — update scheduled task
 // ---------------------------------------------------------------------------
 
-scheduledTasks.put("/:id", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
+authed.openapi(
+  updateTaskRoute,
+  async (c) => {
+    return runEffect(c, Effect.gen(function* () {
+      const { requestId } = yield* RequestContext;
+      const { orgId } = yield* AuthContext;
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
-
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
-  }
-  const { authResult } = preamble;
-
-  const id = c.req.param("id");
-  if (!UUID_RE.test(id)) {
-    return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
-  }
-
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    let body: unknown;
-    try {
-      body = await req.json();
-    } catch {
-      return c.json({ error: "invalid_request", message: "Invalid JSON body." }, 400);
-    }
+      const { id } = c.req.valid("param");
+      if (!UUID_RE.test(id)) {
+        return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
+      }
 
-    const parsed = UpdateScheduledTaskSchema.safeParse(body);
-    if (!parsed.success) {
-      const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-      return c.json({ error: "invalid_request", message: issues }, 400);
-    }
+      const parsed = c.req.valid("json");
 
-    // Validate cron if provided
-    if (parsed.data.cronExpression) {
-      const cronCheck = validateCronExpression(parsed.data.cronExpression);
-      if (!cronCheck.valid) {
-        return c.json({ error: "invalid_request", message: `Invalid cron expression: ${cronCheck.error}` }, 400);
+      // Validate cron if provided
+      if (parsed.cronExpression) {
+        const cronCheck = validateCronExpression(parsed.cronExpression);
+        if (!cronCheck.valid) {
+          return c.json({ error: "invalid_request", message: `Invalid cron expression: ${cronCheck.error}` }, 400);
+        }
       }
-    }
 
-    const result = await updateScheduledTask(id, authResult.user?.id ?? "anonymous", parsed.data);
-    if (!result.ok) {
-      const fail = crudFailResponse(result.reason);
-      return c.json(fail.body, fail.status);
-    }
+      const updateResult = yield* Effect.promise(() => updateScheduledTask(id, { orgId }, parsed));
+      if (!updateResult.ok) {
+        const fail = crudFailResponse(updateResult.reason, requestId);
+        return c.json(fail.body, fail.status);
+      }
 
-    // Fetch updated task to return
-    const updated = await getScheduledTask(id, authResult.user?.id);
-    if (!updated.ok) {
-      return c.json({ ok: true });
+      // Fetch updated task to return
+      const updated = yield* Effect.promise(() => getScheduledTask(id, { orgId }));
+      if (!updated.ok) {
+        return c.json({ ok: true }, 200);
+      }
+      return c.json(updated.data, 200);
+    }), { label: "update scheduled task" });
+  },
+  (result, c) => {
+    if (!result.success) {
+      return c.json(
+        { error: "validation_error", message: "Invalid request body.", details: result.error.issues },
+        422,
+      );
     }
-    return c.json(updated.data);
-  });
-});
+  },
+);
 
 // ---------------------------------------------------------------------------
 // DELETE /:id — soft delete (disable)
 // ---------------------------------------------------------------------------
 
-scheduledTasks.delete("/:id", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
-
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
-
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
-  }
-  const { authResult } = preamble;
+authed.openapi(deleteTaskRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { orgId } = yield* AuthContext;
 
-  const id = c.req.param("id");
-  if (!UUID_RE.test(id)) {
-    return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
-  }
+    const { id } = c.req.valid("param");
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
+    }
 
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    const result = await deleteScheduledTask(id, authResult.user?.id);
-    if (!result.ok) {
-      const fail = crudFailResponse(result.reason);
+    const delResult = yield* Effect.promise(() => deleteScheduledTask(id, { orgId }));
+    if (!delResult.ok) {
+      const fail = crudFailResponse(delResult.reason, requestId);
       return c.json(fail.body, fail.status);
     }
     return c.body(null, 204);
-  });
+  }), { label: "delete scheduled task" });
 });
 
 // ---------------------------------------------------------------------------
 // POST /:id/run — trigger immediate execution
 // ---------------------------------------------------------------------------
 
-scheduledTasks.post("/:id/run", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
+authed.openapi(triggerTaskRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { orgId } = yield* AuthContext;
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
+    const { id } = c.req.valid("param");
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
+    }
 
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
-  }
-  const { authResult } = preamble;
+    const task = yield* Effect.promise(() => getScheduledTask(id, { orgId }));
+    if (!task.ok) {
+      const fail = crudFailResponse(task.reason, requestId);
+      return c.json(fail.body, fail.status);
+    }
 
-  const id = c.req.param("id");
-  if (!UUID_RE.test(id)) {
-    return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
-  }
+    const { triggerTask } = yield* Effect.promise(() => import("@atlas/api/lib/scheduler/engine"));
+    yield* Effect.promise(() => triggerTask(id));
+    return c.json({ message: "Task triggered successfully.", taskId: id }, 200);
+  }), { label: "trigger task execution" });
+});
+
+// ---------------------------------------------------------------------------
+// POST /:id/preview — dry-run delivery format with mock data
+// ---------------------------------------------------------------------------
 
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    const task = await getScheduledTask(id, authResult.user?.id);
+authed.openapi(previewTaskRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { orgId } = yield* AuthContext;
+
+    const { id } = c.req.valid("param");
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
+    }
+
+    const task = yield* Effect.promise(() => getScheduledTask(id, { orgId }));
     if (!task.ok) {
-      const fail = crudFailResponse(task.reason);
+      const fail = crudFailResponse(task.reason, requestId);
       return c.json(fail.body, fail.status);
     }
 
-    try {
-      const { triggerTask } = await import("@atlas/api/lib/scheduler/engine");
-      await triggerTask(id);
-      return c.json({ message: "Task triggered successfully.", taskId: id });
-    } catch (err) {
-      log.error({ err: err instanceof Error ? err.message : String(err), taskId: id }, "Trigger failed");
-      return c.json({ error: "internal_error", message: "Failed to trigger task execution." }, 500);
-    }
-  });
+    const { generateDeliveryPreview } = yield* Effect.promise(() => import("@atlas/api/lib/scheduler/preview"));
+    const preview = generateDeliveryPreview(task.data);
+    return c.json(preview, 200);
+  }), { label: "generate delivery preview" });
 });
 
 // ---------------------------------------------------------------------------
 // GET /:id/runs — list past runs
 // ---------------------------------------------------------------------------
 
-scheduledTasks.get("/:id/runs", async (c) => {
-  const req = c.req.raw;
-  const requestId = crypto.randomUUID();
+authed.openapi(listTaskRunsRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { orgId } = yield* AuthContext;
 
-  if (!hasInternalDB()) {
-    return c.json({ error: "not_available", message: "Scheduled tasks require an internal database." }, 404);
-  }
-
-  const preamble = await authPreamble(req, requestId);
-  if ("error" in preamble) {
-    return c.json(preamble.error, { status: preamble.status, headers: preamble.headers });
-  }
-  const { authResult } = preamble;
-
-  const id = c.req.param("id");
-  if (!UUID_RE.test(id)) {
-    return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
-  }
+    const { id } = c.req.valid("param");
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: "invalid_request", message: "Invalid task ID format." }, 400);
+    }
 
-  return withRequestContext({ requestId, user: authResult.user }, async () => {
-    // Verify task ownership
-    const task = await getScheduledTask(id, authResult.user?.id);
+    // Verify task belongs to this org
+    const task = yield* Effect.promise(() => getScheduledTask(id, { orgId }));
     if (!task.ok) {
-      const fail = crudFailResponse(task.reason);
+      const fail = crudFailResponse(task.reason, requestId);
       return c.json(fail.body, fail.status);
     }
 
-    const rawLimit = parseInt(c.req.query("limit") ?? "20", 10);
-    const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, 100) : 20;
-    const runs = await listTaskRuns(id, { limit });
-    return c.json({ runs });
-  });
+    const { limit } = parsePagination(c, { limit: 20, maxLimit: 100 });
+    const runs = yield* Effect.promise(() => listTaskRuns(id, { limit }));
+    return c.json({ runs }, 200);
+  }), { label: "list task runs" });
 });
 
+// Mount authenticated routes on the outer app
+scheduledTasks.route("/", authed);
+
 export { scheduledTasks };