@yattalo/task-system 0.3.6 → 0.5.0

package/templates/uca/cronManager.ts

@@ -0,0 +1,255 @@
+import { internalMutation, mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+import { computeNextCronRun, parseCronExpression } from "./cronUtils";
+
+const laneValidator = v.union(v.literal("main"), v.literal("cron"), v.literal("subagent"));
+
+const priorityValidator = v.union(
+  v.literal("critical"),
+  v.literal("high"),
+  v.literal("medium"),
+  v.literal("low"),
+);
+
+function makeId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export const listSchedules = query({
+  args: {
+    enabled: v.optional(v.boolean()),
+    lane: v.optional(laneValidator),
+  },
+  handler: async (ctx, args) => {
+    let schedules = await ctx.db.query("cronSchedules").collect();
+    if (args.enabled !== undefined) {
+      schedules = schedules.filter((schedule) => schedule.enabled === args.enabled);
+    }
+    if (args.lane) schedules = schedules.filter((schedule) => schedule.lane === args.lane);
+    return schedules.sort((a, b) => (a.nextRunAt ?? Number.MAX_SAFE_INTEGER) - (b.nextRunAt ?? Number.MAX_SAFE_INTEGER));
+  },
+});
+
+export const createSchedule = mutation({
+  args: {
+    scheduleId: v.optional(v.string()),
+    name: v.string(),
+    jobId: v.optional(v.string()),
+    lane: laneValidator,
+    cronExpression: v.string(),
+    timezone: v.optional(v.string()),
+    createdBy: v.string(),
+    enabled: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    parseCronExpression(args.cronExpression);
+
+    const now = Date.now();
+    const scheduleId = args.scheduleId ?? makeId("cron");
+    const nextRunAt = computeNextCronRun(args.cronExpression, now);
+
+    await ctx.db.insert("cronSchedules", {
+      scheduleId,
+      name: args.name,
+      jobId: args.jobId,
+      lane: args.lane,
+      cronExpression: args.cronExpression,
+      timezone: args.timezone,
+      enabled: args.enabled ?? true,
+      lastRunAt: undefined,
+      nextRunAt,
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    return { scheduleId, nextRunAt };
+  },
+});
+
+export const updateSchedule = mutation({
+  args: {
+    scheduleId: v.string(),
+    name: v.optional(v.string()),
+    cronExpression: v.optional(v.string()),
+    timezone: v.optional(v.string()),
+    enabled: v.optional(v.boolean()),
+    lane: v.optional(laneValidator),
+    jobId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const schedule = await ctx.db
+      .query("cronSchedules")
+      .withIndex("by_scheduleId", (q: any) => q.eq("scheduleId", args.scheduleId))
+      .first();
+    if (!schedule) throw new Error(`Schedule ${args.scheduleId} not found`);
+
+    const patch: Record<string, unknown> = {
+      updatedAt: Date.now(),
+    };
+
+    if (args.name !== undefined) patch.name = args.name;
+    if (args.cronExpression !== undefined) {
+      parseCronExpression(args.cronExpression);
+      patch.cronExpression = args.cronExpression;
+      patch.nextRunAt = computeNextCronRun(args.cronExpression, Date.now());
+    }
+    if (args.timezone !== undefined) patch.timezone = args.timezone;
+    if (args.enabled !== undefined) patch.enabled = args.enabled;
+    if (args.lane !== undefined) patch.lane = args.lane;
+    if (args.jobId !== undefined) patch.jobId = args.jobId;
+
+    await ctx.db.patch(schedule._id, patch);
+  },
+});
+
+export const deleteSchedule = mutation({
+  args: { scheduleId: v.string() },
+  handler: async (ctx, { scheduleId }) => {
+    const schedule = await ctx.db
+      .query("cronSchedules")
+      .withIndex("by_scheduleId", (q: any) => q.eq("scheduleId", scheduleId))
+      .first();
+    if (!schedule) return;
+    await ctx.db.delete(schedule._id);
+  },
+});
+
+export const enqueue = mutation({
+  args: {
+    lane: laneValidator,
+    taskId: v.optional(v.string()),
+    jobId: v.optional(v.string()),
+    runId: v.optional(v.string()),
+    agent: v.optional(v.string()),
+    payload: v.optional(v.any()),
+    priority: v.optional(priorityValidator),
+    availableAt: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const queueId = makeId("queue");
+    await ctx.db.insert("executionQueue", {
+      queueId,
+      lane: args.lane,
+      status: "queued",
+      taskId: args.taskId,
+      jobId: args.jobId,
+      runId: args.runId,
+      agent: args.agent,
+      payload: args.payload,
+      priority: args.priority ?? "medium",
+      attempts: 0,
+      availableAt: args.availableAt ?? now,
+      createdAt: now,
+      updatedAt: now,
+    });
+    return { queueId };
+  },
+});
+
+export const completeQueueItem = mutation({
+  args: {
+    queueId: v.string(),
+    status: v.union(v.literal("done"), v.literal("failed"), v.literal("cancelled")),
+    error: v.optional(v.string()),
+  },
+  handler: async (ctx, { queueId, status, error }) => {
+    const item = await ctx.db
+      .query("executionQueue")
+      .withIndex("by_queueId", (q: any) => q.eq("queueId", queueId))
+      .first();
+    if (!item) throw new Error(`Queue item ${queueId} not found`);
+
+    await ctx.db.patch(item._id, {
+      status,
+      completedAt: Date.now(),
+      updatedAt: Date.now(),
+      payload: {
+        ...(item.payload ?? {}),
+        error,
+      },
+    });
+  },
+});
+
+export const internalDispatchDueSchedules = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    const schedules = await ctx.db.query("cronSchedules").collect();
+    const due = schedules.filter(
+      (schedule) => schedule.enabled && typeof schedule.nextRunAt === "number" && schedule.nextRunAt <= now,
+    );
+
+    const dispatched: Array<{ scheduleId: string; queueId: string; runId?: string }> = [];
+
+    for (const schedule of due) {
+      let runId: string | undefined;
+      let taskId: string | undefined;
+      let agent: string | undefined;
+
+      if (schedule.jobId) {
+        const job = await ctx.db
+          .query("agentOpsJobs")
+          .withIndex("by_jobId", (q: any) => q.eq("jobId", schedule.jobId))
+          .first();
+
+        if (job && job.enabled && job.status === "active") {
+          runId = makeId(`run-${job.jobId}`);
+          taskId = job.taskId;
+          agent = job.agent;
+          await ctx.db.insert("agentOpsRuns", {
+            runId,
+            jobId: job.jobId,
+            taskId: job.taskId,
+            agent: job.agent,
+            lane: job.lane,
+            status: "queued",
+            triggeredBy: "schedule",
+            queuedAt: now,
+            logs: [{ timestamp: now, level: "info", message: `Queued from schedule ${schedule.scheduleId}` }],
+            metadata: { scheduleId: schedule.scheduleId },
+          });
+
+          await ctx.db.patch(job._id, {
+            totalRuns: job.totalRuns + 1,
+            updatedAt: now,
+          });
+        }
+      }
+
+      const queueId = makeId("queue");
+      await ctx.db.insert("executionQueue", {
+        queueId,
+        lane: schedule.lane,
+        status: "queued",
+        taskId,
+        jobId: schedule.jobId,
+        runId,
+        agent,
+        payload: { scheduleId: schedule.scheduleId, source: "internalDispatchDueSchedules" },
+        priority: "medium",
+        attempts: 0,
+        availableAt: now,
+        createdAt: now,
+        updatedAt: now,
+      });
+
+      const nextRunAt = computeNextCronRun(schedule.cronExpression, now);
+      await ctx.db.patch(schedule._id, {
+        lastRunAt: now,
+        nextRunAt,
+        updatedAt: now,
+      });
+
+      dispatched.push({ scheduleId: schedule.scheduleId, queueId, runId });
+    }
+
+    return {
+      scanned: schedules.length,
+      due: due.length,
+      dispatched,
+    };
+  },
+});

package/templates/uca/cronUtils.ts

@@ -0,0 +1,99 @@
+export type ParsedCron = {
+  minute: number[];
+  hour: number[];
+  day: number[];
+  month: number[];
+  weekday: number[];
+};
+
+const FIELD_LIMITS: Array<[number, number]> = [
+  [0, 59],
+  [0, 23],
+  [1, 31],
+  [1, 12],
+  [0, 6],
+];
+
+function expandRange(part: string, min: number, max: number): number[] {
+  if (part === "*") {
+    const values: number[] = [];
+    for (let value = min; value <= max; value += 1) values.push(value);
+    return values;
+  }
+
+  const stepParts = part.split("/");
+  const base = stepParts[0];
+  const step = stepParts[1] ? Number(stepParts[1]) : 1;
+  if (!Number.isFinite(step) || step <= 0) throw new Error(`Invalid cron step: ${part}`);
+
+  const [startRaw, endRaw] = base.includes("-") ? base.split("-") : [base, base];
+  const start = startRaw === "*" ? min : Number(startRaw);
+  const end = endRaw === "*" ? max : Number(endRaw);
+
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error(`Invalid cron range: ${part}`);
+  }
+  if (start < min || end > max || start > end) {
+    throw new Error(`Cron range out of bounds: ${part}`);
+  }
+
+  const values: number[] = [];
+  for (let value = start; value <= end; value += step) values.push(value);
+  return values;
+}
+
+function parseField(field: string, min: number, max: number): number[] {
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    for (const value of expandRange(trimmed, min, max)) {
+      values.add(value);
+    }
+  }
+  if (values.size === 0) {
+    throw new Error(`Invalid cron field: ${field}`);
+  }
+  return [...values].sort((a, b) => a - b);
+}
+
+export function parseCronExpression(expression: string): ParsedCron {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error("Cron expression must have 5 fields: minute hour day month weekday");
+  }
+  return {
+    minute: parseField(parts[0]!, ...FIELD_LIMITS[0]),
+    hour: parseField(parts[1]!, ...FIELD_LIMITS[1]),
+    day: parseField(parts[2]!, ...FIELD_LIMITS[2]),
+    month: parseField(parts[3]!, ...FIELD_LIMITS[3]),
+    weekday: parseField(parts[4]!, ...FIELD_LIMITS[4]),
+  };
+}
+
+function isMatch(parsed: ParsedCron, date: Date): boolean {
+  return (
+    parsed.minute.includes(date.getMinutes()) &&
+    parsed.hour.includes(date.getHours()) &&
+    parsed.day.includes(date.getDate()) &&
+    parsed.month.includes(date.getMonth() + 1) &&
+    parsed.weekday.includes(date.getDay())
+  );
+}
+
+export function computeNextCronRun(expression: string, fromTimestamp: number): number {
+  const parsed = parseCronExpression(expression);
+  const candidate = new Date(fromTimestamp);
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+
+  const maxIterations = 60 * 24 * 90;
+  for (let i = 0; i < maxIterations; i += 1) {
+    if (isMatch(parsed, candidate)) {
+      return candidate.getTime();
+    }
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+
+  throw new Error(`Unable to compute next run for cron: ${expression}`);
+}

package/templates/uca/driftEvents.ts

@@ -0,0 +1,106 @@
+import { query, mutation } from "../_generated/server";
+import { v } from "convex/values";
+
+export const list = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("driftEvents").collect();
+  },
+});
+
+export const stats = query({
+  handler: async (ctx) => {
+    const all = await ctx.db.query("driftEvents").collect();
+    const bySeverity: Record<string, number> = {};
+    const byStatus: Record<string, number> = {};
+    for (const drift of all) {
+      bySeverity[drift.severity] = (bySeverity[drift.severity] ?? 0) + 1;
+      byStatus[drift.status] = (byStatus[drift.status] ?? 0) + 1;
+    }
+    const open = all.filter((d) => d.status === "open");
+    const critical = all.filter((d) => d.severity === "high" && d.status === "open");
+    return {
+      total: all.length,
+      open: open.length,
+      critical: critical.length,
+      bySeverity,
+      byStatus,
+    };
+  },
+});
+
+export const create = mutation({
+  args: {
+    eventId: v.string(),
+    projectId: v.string(),
+    taskId: v.optional(v.string()),
+    agent: v.string(),
+    driftType: v.string(),
+    description: v.string(),
+    severity: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("driftEvents", {
+      ...args,
+      status: "open",
+      detectedAt: Date.now(),
+    } as any);
+  },
+});
+
+export const resolve = mutation({
+  args: {
+    eventId: v.string(),
+    resolvedBy: v.string(),
+    resolution: v.string(),
+  },
+  handler: async (ctx, { eventId, resolvedBy, resolution }) => {
+    const event = await ctx.db
+      .query("driftEvents")
+      .filter((q) => q.eq(q.field("eventId"), eventId))
+      .first();
+    if (!event) throw new Error(`Drift event ${eventId} not found`);
+    await ctx.db.patch(event._id, {
+      status: "resolved",
+      resolvedBy,
+      resolvedAt: Date.now(),
+      resolution,
+    } as any);
+  },
+});
+
+export const dismiss = mutation({
+  args: {
+    eventId: v.string(),
+    dismissedBy: v.string(),
+  },
+  handler: async (ctx, { eventId, dismissedBy }) => {
+    const event = await ctx.db
+      .query("driftEvents")
+      .filter((q) => q.eq(q.field("eventId"), eventId))
+      .first();
+    if (!event) throw new Error(`Drift event ${eventId} not found`);
+    await ctx.db.patch(event._id, {
+      status: "dismissed",
+      resolvedBy: dismissedBy,
+      resolvedAt: Date.now(),
+    } as any);
+  },
+});
+
+export const acknowledge = mutation({
+  args: {
+    eventId: v.string(),
+    acknowledgedBy: v.string(),
+  },
+  handler: async (ctx, { eventId, acknowledgedBy }) => {
+    const event = await ctx.db
+      .query("driftEvents")
+      .filter((q) => q.eq(q.field("eventId"), eventId))
+      .first();
+    if (!event) throw new Error(`Drift event ${eventId} not found`);
+    await ctx.db.patch(event._id, {
+      status: "acknowledged",
+      resolvedBy: acknowledgedBy,
+    } as any);
+  },
+});

package/templates/uca/heartbeats.ts

@@ -0,0 +1,167 @@
+import { internalMutation, mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+const DEFAULT_TTL_SECONDS = 300;
+const YELLOW_WINDOW_MS = 60_000;
+
+function classifyHeartbeat(now: number, expiresAt: number): "green" | "yellow" | "red" {
+  if (expiresAt <= now) return "red";
+  if (expiresAt - now <= YELLOW_WINDOW_MS) return "yellow";
+  return "green";
+}
+
+function mapHeartbeatToAgentStatus(status: "green" | "yellow" | "red"): "active" | "idle" | "offline" {
+  if (status === "green") return "active";
+  if (status === "yellow") return "idle";
+  return "offline";
+}
+
+async function syncRegistryStatus(ctx: any, agentId: string, heartbeatStatus: "green" | "yellow" | "red"): Promise<void> {
+  const agent = await ctx.db
+    .query("agentRegistry")
+    .withIndex("by_agentId", (q: any) => q.eq("agentId", agentId))
+    .first();
+  if (!agent) return;
+  const currentStatus = mapHeartbeatToAgentStatus(heartbeatStatus);
+  if (agent.currentStatus === currentStatus) return;
+  await ctx.db.patch(agent._id, { currentStatus });
+}
+
+export const beat = mutation({
+  args: {
+    agentId: v.string(),
+    sessionId: v.optional(v.string()),
+    ttlSeconds: v.optional(v.number()),
+    latencyMs: v.optional(v.number()),
+    details: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const ttlMs = (args.ttlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
+    const expiresAt = now + ttlMs;
+    const status = classifyHeartbeat(now, expiresAt);
+
+    const existing = await ctx.db
+      .query("agentHeartbeats")
+      .withIndex("by_agentId", (q: any) => q.eq("agentId", args.agentId))
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        sessionId: args.sessionId,
+        protocol: "HEARTBEAT_OK",
+        status,
+        heartbeatAt: now,
+        lastSeenAt: now,
+        expiresAt,
+        latencyMs: args.latencyMs,
+        details: args.details,
+        updatedAt: now,
+      });
+    } else {
+      await ctx.db.insert("agentHeartbeats", {
+        agentId: args.agentId,
+        sessionId: args.sessionId,
+        protocol: "HEARTBEAT_OK",
+        status,
+        heartbeatAt: now,
+        lastSeenAt: now,
+        expiresAt,
+        latencyMs: args.latencyMs,
+        details: args.details,
+        updatedAt: now,
+      });
+    }
+
+    await syncRegistryStatus(ctx, args.agentId, status);
+
+    return {
+      agentId: args.agentId,
+      status,
+      heartbeatAt: now,
+      expiresAt,
+      protocol: "HEARTBEAT_OK",
+    };
+  },
+});
+
+export const getAgentHeartbeat = query({
+  args: { agentId: v.string() },
+  handler: async (ctx, { agentId }) => {
+    const record = await ctx.db
+      .query("agentHeartbeats")
+      .withIndex("by_agentId", (q: any) => q.eq("agentId", agentId))
+      .first();
+    if (!record) return null;
+
+    const now = Date.now();
+    const computed = classifyHeartbeat(now, record.expiresAt);
+    return {
+      ...record,
+      computedStatus: computed,
+      msUntilExpiry: Math.max(0, record.expiresAt - now),
+    };
+  },
+});
+
+export const listHeartbeats = query({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    const heartbeats = await ctx.db.query("agentHeartbeats").collect();
+    return heartbeats
+      .map((record) => ({
+        ...record,
+        computedStatus: classifyHeartbeat(now, record.expiresAt),
+        msUntilExpiry: Math.max(0, record.expiresAt - now),
+      }))
+      .sort((a, b) => b.lastSeenAt - a.lastSeenAt);
+  },
+});
+
+export const statusSummary = query({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    const all = await ctx.db.query("agentHeartbeats").collect();
+    const byStatus: Record<string, number> = { green: 0, yellow: 0, red: 0 };
+    for (const heartbeat of all) {
+      const status = classifyHeartbeat(now, heartbeat.expiresAt);
+      byStatus[status] += 1;
+    }
+    return {
+      total: all.length,
+      byStatus,
+      healthy: byStatus.green,
+      degraded: byStatus.yellow,
+      offline: byStatus.red,
+    };
+  },
+});
+
+export const internalSweepStaleHeartbeats = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    const all = await ctx.db.query("agentHeartbeats").collect();
+    const updates: Array<{ agentId: string; from: string; to: string }> = [];
+
+    for (const heartbeat of all) {
+      const nextStatus = classifyHeartbeat(now, heartbeat.expiresAt);
+      if (heartbeat.status !== nextStatus) {
+        await ctx.db.patch(heartbeat._id, {
+          status: nextStatus,
+          updatedAt: now,
+        });
+        updates.push({ agentId: heartbeat.agentId, from: heartbeat.status, to: nextStatus });
+      }
+      await syncRegistryStatus(ctx, heartbeat.agentId, nextStatus);
+    }
+
+    return {
+      scanned: all.length,
+      updated: updates.length,
+      updates,
+    };
+  },
+});