negotium 0.1.8 → 0.1.10

package/dist/runtime/cron/module.ts

@@ -0,0 +1,169 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  cancelDeferredInject,
+  logger,
+  type NegotiumNodeModule,
+  triggerTopicAiTurn,
+} from "@negotium/core";
+import { listCronBackgroundSessions } from "#background-sessions";
+import { resetCronTopicContext } from "#context";
+import { type CronHost, configureCronHost, cronHost } from "#host";
+import { CronScheduler, type CronSchedulerOptions } from "#scheduler";
+import { runCronPromptScript } from "#scripts";
+import {
+  type CronDatabase,
+  configureCronDatabase,
+  ensureCronSchema,
+  listOrphanedCronTopicSessions,
+} from "#store";
+
+const SOURCE_MCP_SERVER_FILE = fileURLToPath(new URL("./mcp-server.ts", import.meta.url));
+const PACKAGED_MCP_SERVER_FILE = fileURLToPath(
+  new URL("./runtime/cron/mcp-server.ts", import.meta.url),
+);
+
+export interface CronModuleOptions {
+  pollIntervalMs?: number;
+  runTimeoutMs?: number;
+  queueTimeoutMs?: number;
+  scriptTimeoutMs?: number;
+  database?: CronDatabase;
+  host?: Partial<CronHost>;
+  mcpServerFile?: string;
+}
+
+function envMs(name: string, fallback: number): number {
+  const parsed = Number.parseInt(process.env[name] ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function createCronModule(options: CronModuleOptions = {}): NegotiumNodeModule {
+  return {
+    name: "cron",
+    singleton: true,
+    capabilities: ["scheduler.cron.v1", "scheduler.cron.v2"],
+    start(context) {
+      const restoreDatabase = options.database ? configureCronDatabase(options.database) : () => {};
+      const restoreHost = configureCronHost(options.host ?? {});
+      const host = cronHost();
+      ensureCronSchema();
+      const cleanupTasks = new Set<Promise<unknown>>();
+      const trackCleanup = (promise: Promise<unknown>) => {
+        cleanupTasks.add(promise);
+        void promise.then(
+          () => cleanupTasks.delete(promise),
+          (error) => {
+            cleanupTasks.delete(promise);
+            logger.warn({ err: error }, "cron: topic context cleanup failed");
+          },
+        );
+      };
+      for (const topicId of new Set(
+        listOrphanedCronTopicSessions().map((entry) => entry.topicId),
+      )) {
+        trackCleanup(resetCronTopicContext(topicId));
+      }
+      const unsubscribeTopicCleanup = context.bus.subscribe((event) => {
+        if (event.type === "topic-deleted") trackCleanup(resetCronTopicContext(event.topicId));
+      });
+      const mcpServerFile =
+        options.mcpServerFile ??
+        (existsSync(SOURCE_MCP_SERVER_FILE) ? SOURCE_MCP_SERVER_FILE : PACKAGED_MCP_SERVER_FILE);
+      const unregisterMcp = host.registerRuntimeMcpServer("cron-manager", {
+        scopes: ["forum", "manager"],
+        forumRequired: true,
+        build({ userId, session, topicId, agent }) {
+          const args = [`--user-id=${userId}`, `--topic=${session}`];
+          if (topicId) args.push(`--topic-id=${topicId}`);
+          if (host.authorize?.(userId, "cron:admin", { type: "cron" })) {
+            args.push("--authorized=true");
+          }
+          return host.buildStdioMcpServer(agent, mcpServerFile, args);
+        },
+      });
+      const unregisterBackgroundSessions = host.registerBackgroundSessionProvider(
+        listCronBackgroundSessions,
+      );
+
+      const schedulerOptions: CronSchedulerOptions = {
+        bus: context.bus,
+        pollIntervalMs: options.pollIntervalMs ?? envMs("NEGOTIUM_CRON_POLL_INTERVAL_MS", 1_000),
+        runTimeoutMs: options.runTimeoutMs ?? envMs("NEGOTIUM_CRON_RUN_TIMEOUT_MS", 10 * 60_000),
+        queueTimeoutMs:
+          options.queueTimeoutMs ?? envMs("NEGOTIUM_CRON_QUEUE_TIMEOUT_MS", 5 * 60_000),
+        dispatch:
+          options.host?.dispatch ??
+          (async (job, run, hooks, execution) => {
+            const taskPrompt =
+              job.prompt ??
+              (await runCronPromptScript({
+                script: job.script!,
+                cwd: host.resolveTopicWorkspaceDir(job.topicId),
+                jobId: job.id,
+                topicId: job.topicId,
+                timeoutMs:
+                  options.scriptTimeoutMs ?? envMs("NEGOTIUM_CRON_SCRIPT_TIMEOUT_MS", 10 * 60_000),
+                signal: execution.signal,
+              }));
+            if (!taskPrompt.trim()) {
+              return { status: "skipped", reason: "prompt script produced no output" } as const;
+            }
+            if (!host.getTopic(job.topicId)?.agent)
+              throw new Error("target topic was deleted during run");
+            const prompt = [
+              `<scheduled-task name="${job.name}" run-id="${run.id}">`,
+              "This is a background scheduled run. Do not ask interactive questions.",
+              "All scheduled tasks in this topic share one Cron conversation.",
+              "Use relevant conclusions and state from previous scheduled runs before acting.",
+              "Complete the task and report only meaningful results in the user's language.",
+              taskPrompt,
+              "</scheduled-task>",
+            ].join("\n");
+            const requestId = `cron:${run.id}`;
+            const queryId = triggerTopicAiTurn(
+              job.topicId,
+              job.ownerUserId,
+              prompt,
+              execution.agent,
+              {
+                origin: `cron:${job.id}:${run.id}`,
+                requestId,
+                hideInjectMessage: true,
+                modelOverride: job.model,
+                effortOverride: job.effort,
+                sessionId: execution.sessionId ?? null,
+                sessionName: execution.sessionName,
+                sessionType: "cron",
+                onDispatched: hooks.onDispatched,
+                onSessionId: hooks.onSessionId,
+                onSessionReset: hooks.onSessionReset,
+                bridgeSessionFromHistory: true,
+                onSettled: hooks.onSettled,
+              },
+            );
+            return {
+              status: queryId ? ("dispatched" as const) : ("deferred" as const),
+              requestId,
+              ...(queryId ? { queryId } : {}),
+              cancel: () => cancelDeferredInject(job.topicId, requestId),
+            };
+          }),
+      };
+      const scheduler = new CronScheduler(schedulerOptions);
+      scheduler.start();
+
+      return {
+        async stop() {
+          scheduler.stop();
+          unsubscribeTopicCleanup();
+          unregisterBackgroundSessions();
+          unregisterMcp();
+          await Promise.allSettled(cleanupTasks);
+          restoreHost();
+          restoreDatabase();
+        },
+      };
+    },
+  };
+}

package/dist/runtime/cron/schedule.ts

@@ -0,0 +1,211 @@
+const FIELD_RANGES = [
+  [0, 59],
+  [0, 23],
+  [1, 31],
+  [1, 12],
+  [0, 7],
+] as const;
+
+interface ParsedField {
+  values: Set<number>;
+  wildcard: boolean;
+}
+
+export interface ParsedCronExpression {
+  minute: ParsedField;
+  hour: ParsedField;
+  dayOfMonth: ParsedField;
+  month: ParsedField;
+  dayOfWeek: ParsedField;
+}
+
+function parseNumber(raw: string, min: number, max: number): number {
+  if (!/^\d+$/.test(raw)) throw new Error(`invalid cron value: ${raw}`);
+  const value = Number.parseInt(raw, 10);
+  if (value < min || value > max) {
+    throw new Error(`cron value ${value} is outside ${min}-${max}`);
+  }
+  return value;
+}
+
+function parseField(raw: string, min: number, max: number, normalize?: (n: number) => number) {
+  const values = new Set<number>();
+  const wildcard = raw === "*";
+  for (const item of raw.split(",")) {
+    if (!item) throw new Error("empty cron list item");
+    const [base, stepRaw, extra] = item.split("/");
+    if (extra !== undefined) throw new Error(`invalid cron step: ${item}`);
+    const step = stepRaw === undefined ? 1 : parseNumber(stepRaw, 1, max - min + 1);
+    let start: number;
+    let end: number;
+    if (base === "*") {
+      start = min;
+      end = max;
+    } else if (base.includes("-")) {
+      const [startRaw, endRaw, rangeExtra] = base.split("-");
+      if (!startRaw || !endRaw || rangeExtra !== undefined) {
+        throw new Error(`invalid cron range: ${base}`);
+      }
+      start = parseNumber(startRaw, min, max);
+      end = parseNumber(endRaw, min, max);
+      if (end < start) throw new Error(`descending cron range: ${base}`);
+    } else {
+      start = parseNumber(base, min, max);
+      end = stepRaw === undefined ? start : max;
+    }
+    for (let value = start; value <= end; value += step) {
+      values.add(normalize ? normalize(value) : value);
+    }
+  }
+  return { values, wildcard } satisfies ParsedField;
+}
+
+export function parseCronExpression(expression: string): ParsedCronExpression {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error("cron expression must have exactly 5 fields");
+  const parsed = fields.map((field, index) => {
+    const [min, max] = FIELD_RANGES[index]!;
+    return parseField(
+      field!,
+      min,
+      max,
+      index === 4 ? (value) => (value === 7 ? 0 : value) : undefined,
+    );
+  });
+  return {
+    minute: parsed[0]!,
+    hour: parsed[1]!,
+    dayOfMonth: parsed[2]!,
+    month: parsed[3]!,
+    dayOfWeek: parsed[4]!,
+  };
+}
+
+export function validateCronExpression(
+  expression: string,
+): { ok: true } | { ok: false; error: string } {
+  try {
+    parseCronExpression(expression);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+export function normalizeCronTimezone(timezone?: string | null): string | undefined {
+  const value = timezone?.trim();
+  if (!value) return undefined;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date());
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function dateParts(date: Date, timezone?: string) {
+  if (!timezone) {
+    return {
+      minute: date.getMinutes(),
+      hour: date.getHours(),
+      dayOfMonth: date.getDate(),
+      month: date.getMonth() + 1,
+      dayOfWeek: date.getDay(),
+    };
+  }
+  let formatter = formatters.get(timezone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    });
+    formatters.set(timezone, formatter);
+  }
+  const values = Object.fromEntries(
+    formatter
+      .formatToParts(date)
+      .filter((part) => part.type !== "literal")
+      .map((part) => [part.type, Number.parseInt(part.value, 10)]),
+  ) as Record<string, number>;
+  const year = values.year!;
+  const month = values.month!;
+  const dayOfMonth = values.day!;
+  return {
+    minute: values.minute!,
+    hour: values.hour!,
+    dayOfMonth,
+    month,
+    dayOfWeek: new Date(Date.UTC(year, month - 1, dayOfMonth)).getUTCDay(),
+  };
+}
+
+export function cronMatchesDate(
+  expression: string | ParsedCronExpression,
+  date: Date,
+  timezone?: string,
+): boolean {
+  const cron = typeof expression === "string" ? parseCronExpression(expression) : expression;
+  const parts = dateParts(date, timezone);
+  return cronMatchesParts(cron, parts);
+}
+
+function cronMatchesParts(
+  cron: ParsedCronExpression,
+  parts: ReturnType<typeof dateParts>,
+): boolean {
+  if (!cron.minute.values.has(parts.minute)) return false;
+  if (!cron.hour.values.has(parts.hour)) return false;
+  if (!cron.month.values.has(parts.month)) return false;
+  const dom = cron.dayOfMonth.values.has(parts.dayOfMonth);
+  const dow = cron.dayOfWeek.values.has(parts.dayOfWeek);
+  const dayMatches = cron.dayOfMonth.wildcard ? dow : cron.dayOfWeek.wildcard ? dom : dom || dow;
+  return dayMatches;
+}
+
+/** Return the next matching real instant, strictly after `after`. */
+export function computeNextCronRun(
+  expression: string,
+  after: Date = new Date(),
+  timezone?: string,
+): Date {
+  const parsed = parseCronExpression(expression);
+  if (timezone && !normalizeCronTimezone(timezone))
+    throw new Error(`invalid timezone: ${timezone}`);
+  const candidate = new Date(after.getTime());
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+  const deadline = candidate.getTime() + 366 * 24 * 60 * 60_000 * 5;
+  while (candidate.getTime() <= deadline) {
+    const parts = dateParts(candidate, timezone);
+    if (cronMatchesParts(parsed, parts)) return candidate;
+
+    const dom = parsed.dayOfMonth.values.has(parts.dayOfMonth);
+    const dow = parsed.dayOfWeek.values.has(parts.dayOfWeek);
+    const dayMatches = parsed.dayOfMonth.wildcard
+      ? dow
+      : parsed.dayOfWeek.wildcard
+        ? dom
+        : dom || dow;
+    if (
+      !parsed.month.values.has(parts.month) ||
+      !dayMatches ||
+      !parsed.hour.values.has(parts.hour)
+    ) {
+      // Skip to the next local-hour boundary. This keeps DST and non-whole-hour
+      // timezone offsets correct while reducing sparse schedules from ~2.6m
+      // minute checks to at most a few thousand hourly checks.
+      const minutes = parts.minute === 0 ? 60 : 60 - parts.minute;
+      candidate.setTime(candidate.getTime() + minutes * 60_000);
+      continue;
+    }
+    candidate.setTime(candidate.getTime() + 60_000);
+  }
+  throw new Error("cron expression has no match within 5 years");
+}