@elizaos/plugin-cron 2.0.0-alpha.3

package/dist/chunk-QQWDOGXP.js

@@ -0,0 +1,1311 @@
+import {
+  __export
+} from "./chunk-MLKGABMK.js";
+
+// src/otto/index.ts
+var otto_exports = {};
+__export(otto_exports, {
+  appendCronRunLog: () => appendCronRunLog,
+  applyJobPatch: () => applyJobPatch,
+  assertDeliverySupport: () => assertDeliverySupport,
+  assertSupportedJobSpec: () => assertSupportedJobSpec,
+  executeOttoJob: () => executeOttoJob,
+  isOttoPayload: () => isOttoPayload,
+  loadCronStore: () => loadCronStore,
+  migrateLegacyCronPayload: () => migrateLegacyCronPayload,
+  normalizeCronJobCreate: () => normalizeCronJobCreate,
+  normalizeCronJobInput: () => normalizeCronJobInput,
+  normalizeCronJobPatch: () => normalizeCronJobPatch,
+  normalizeOptionalAgentId: () => normalizeOptionalAgentId,
+  normalizeOptionalText: () => normalizeOptionalText,
+  normalizeRequiredName: () => normalizeRequiredName,
+  parseAbsoluteTimeMs: () => parseAbsoluteTimeMs,
+  readCronRunLogEntries: () => readCronRunLogEntries,
+  resolveCronDeliveryPlan: () => resolveCronDeliveryPlan,
+  resolveCronRunLogPath: () => resolveCronRunLogPath,
+  resolveCronStorePath: () => resolveCronStorePath,
+  saveCronStore: () => saveCronStore,
+  validateScheduleTimestamp: () => validateScheduleTimestamp
+});
+
+// src/otto/delivery.ts
+function normalizeChannel(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) {
+    return void 0;
+  }
+  return trimmed;
+}
+function normalizeTo(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function resolveCronDeliveryPlan(job) {
+  const payload = job.payload.kind === "agentTurn" ? job.payload : null;
+  const delivery = job.delivery;
+  const hasDelivery = delivery && typeof delivery === "object";
+  const rawMode = hasDelivery ? delivery.mode : void 0;
+  const mode = rawMode === "announce" ? "announce" : rawMode === "none" ? "none" : rawMode === "deliver" ? "announce" : void 0;
+  const payloadChannel = normalizeChannel(payload?.channel);
+  const payloadTo = normalizeTo(payload?.to);
+  const deliveryChannel = normalizeChannel(
+    delivery?.channel
+  );
+  const deliveryTo = normalizeTo(delivery?.to);
+  const channel = deliveryChannel ?? payloadChannel ?? "last";
+  const to = deliveryTo ?? payloadTo;
+  if (hasDelivery) {
+    const resolvedMode = mode ?? "none";
+    return {
+      mode: resolvedMode,
+      channel,
+      to,
+      source: "delivery",
+      requested: resolvedMode === "announce"
+    };
+  }
+  const legacyMode = payload?.deliver === true ? "explicit" : payload?.deliver === false ? "off" : "auto";
+  const hasExplicitTarget = Boolean(to);
+  const requested = legacyMode === "explicit" || legacyMode === "auto" && hasExplicitTarget;
+  return {
+    mode: requested ? "announce" : "none",
+    channel,
+    to,
+    source: "payload",
+    requested
+  };
+}
+
+// src/otto/detect.ts
+function isOttoPayload(payload) {
+  const kind = payload.kind;
+  return kind === "systemEvent" || kind === "agentTurn";
+}
+
+// src/otto/executor.ts
+import {
+  ChannelType as ChannelType2,
+  logger as logger3,
+  stringToUuid as stringToUuid2
+} from "@elizaos/core";
+import { v4 as uuidv43 } from "uuid";
+
+// src/heartbeat/delivery.ts
+import {
+  logger
+} from "@elizaos/core";
+import { v4 as uuidv4 } from "uuid";
+var LAST_ROUTE_COMPONENT_TYPE = "last_delivery_route";
+var INTERNAL_SOURCES = /* @__PURE__ */ new Set(["cron", "webhook", "heartbeat", "internal"]);
+async function readLastRoute(runtime) {
+  const component = await runtime.getComponent(runtime.agentId, LAST_ROUTE_COMPONENT_TYPE);
+  if (!component?.data) {
+    return null;
+  }
+  const data = component.data;
+  const source = typeof data.source === "string" ? data.source : "";
+  if (!source) {
+    return null;
+  }
+  return {
+    source,
+    channelId: typeof data.channelId === "string" ? data.channelId : void 0
+  };
+}
+async function writeLastRoute(runtime, target) {
+  const existing = await runtime.getComponent(runtime.agentId, LAST_ROUTE_COMPONENT_TYPE);
+  const data = {
+    source: target.source,
+    channelId: target.channelId ?? null,
+    updatedAt: Date.now()
+  };
+  if (existing) {
+    await runtime.updateComponent({
+      ...existing,
+      data
+    });
+  } else {
+    await runtime.createComponent({
+      id: uuidv4(),
+      entityId: runtime.agentId,
+      agentId: runtime.agentId,
+      roomId: runtime.agentId,
+      worldId: runtime.agentId,
+      sourceEntityId: runtime.agentId,
+      type: LAST_ROUTE_COMPONENT_TYPE,
+      data,
+      createdAt: Date.now()
+    });
+  }
+}
+async function scanRoomsForExternalTarget(runtime) {
+  const rooms = await runtime.getRooms(runtime.agentId).catch(() => []);
+  for (const room of rooms) {
+    if (room.source && !INTERNAL_SOURCES.has(room.source)) {
+      return {
+        source: room.source,
+        channelId: room.channelId ?? void 0
+      };
+    }
+  }
+  return null;
+}
+async function resolveDeliveryTarget(runtime, channel, to) {
+  if (channel !== "last") {
+    return { source: channel, channelId: to };
+  }
+  const stored = await readLastRoute(runtime);
+  if (stored) {
+    if (to) {
+      return { source: stored.source, channelId: to };
+    }
+    return stored;
+  }
+  const scanned = await scanRoomsForExternalTarget(runtime);
+  if (scanned) {
+    logger.debug(
+      `[Delivery] Resolved "last" via room scan: ${scanned.source}:${scanned.channelId ?? "(default)"}`
+    );
+    if (to) {
+      return { source: scanned.source, channelId: to };
+    }
+    return scanned;
+  }
+  return null;
+}
+async function deliverToTarget(runtime, content, channel, to, bestEffort) {
+  const target = await resolveDeliveryTarget(runtime, channel, to);
+  if (!target) {
+    const msg = `No delivery target resolved for channel "${channel}"`;
+    if (bestEffort) {
+      logger.warn(`[Delivery] ${msg}`);
+      return null;
+    }
+    throw new Error(msg);
+  }
+  const targetInfo = {
+    source: target.source
+  };
+  if (target.channelId) {
+    targetInfo.channelId = target.channelId;
+  }
+  const deliveryError = await runtime.sendMessageToTarget(targetInfo, content).then(
+    () => null,
+    (err) => err
+  );
+  if (deliveryError) {
+    if (bestEffort) {
+      logger.warn(
+        `[Delivery] Best-effort delivery failed to ${target.source}: ${deliveryError.message}`
+      );
+      return null;
+    }
+    throw deliveryError;
+  }
+  await writeLastRoute(runtime, target).catch((err) => {
+    logger.debug(`[Delivery] Failed to persist last route: ${err.message}`);
+  });
+  logger.info(
+    `[Delivery] Delivered to ${target.source}${target.channelId ? `:${target.channelId}` : ""}`
+  );
+  return target;
+}
+
+// src/heartbeat/queue.ts
+var queues = /* @__PURE__ */ new Map();
+function agentQueue(agentId) {
+  let q = queues.get(agentId);
+  if (!q) {
+    q = [];
+    queues.set(agentId, q);
+  }
+  return q;
+}
+function pushSystemEvent(agentId, text, source) {
+  agentQueue(agentId).push({ text, source, ts: Date.now() });
+}
+function drainSystemEvents(agentId) {
+  const q = queues.get(agentId);
+  if (!q || q.length === 0) {
+    return [];
+  }
+  const events = [...q];
+  q.length = 0;
+  return events;
+}
+function pendingEventCount(agentId) {
+  return queues.get(agentId)?.length ?? 0;
+}
+
+// src/heartbeat/worker.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  ChannelType,
+  logger as logger2,
+  stringToUuid
+} from "@elizaos/core";
+import { v4 as uuidv42 } from "uuid";
+
+// src/heartbeat/config.ts
+var DEFAULT_EVERY_MS = 30 * 60 * 1e3;
+var DEFAULT_PROMPT_FILE = "HEARTBEAT.md";
+function parseDurationToMs(raw) {
+  const match = raw.match(/^(\d+(?:\.\d+)?)\s*(s|sec|m|min|h|hr|d|day|ms)?$/i);
+  if (!match) {
+    return DEFAULT_EVERY_MS;
+  }
+  const value = Number.parseFloat(match[1]);
+  const unit = (match[2] ?? "m").toLowerCase();
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+    case "sec":
+      return value * 1e3;
+    case "m":
+    case "min":
+      return value * 6e4;
+    case "h":
+    case "hr":
+      return value * 36e5;
+    case "d":
+    case "day":
+      return value * 864e5;
+    default:
+      return value * 6e4;
+  }
+}
+function parseActiveHours(raw) {
+  const start = typeof raw.start === "string" ? raw.start.trim() : "";
+  const end = typeof raw.end === "string" ? raw.end.trim() : "";
+  if (!start || !end) {
+    return null;
+  }
+  return { start, end };
+}
+function resolveHeartbeatConfig(runtime) {
+  const settings = runtime.character?.settings ?? {};
+  const hb = settings.heartbeat ?? {};
+  const everyRaw = typeof hb.every === "string" ? hb.every : "";
+  const everyMs = everyRaw ? parseDurationToMs(everyRaw) : DEFAULT_EVERY_MS;
+  const activeHours = hb.activeHours && typeof hb.activeHours === "object" ? parseActiveHours(hb.activeHours) : null;
+  const target = typeof hb.target === "string" ? hb.target.trim() : "last";
+  const promptFile = typeof hb.prompt === "string" && hb.prompt.trim() ? hb.prompt.trim() : DEFAULT_PROMPT_FILE;
+  const enabled = hb.enabled !== false;
+  return { everyMs, activeHours, target, promptFile, enabled };
+}
+function isWithinActiveHours(activeHours) {
+  if (!activeHours) {
+    return true;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const hh = now.getHours();
+  const mm = now.getMinutes();
+  const currentMinutes = hh * 60 + mm;
+  const [startH, startM] = activeHours.start.split(":").map(Number);
+  const [endH, endM] = activeHours.end.split(":").map(Number);
+  const startMinutes = (startH ?? 0) * 60 + (startM ?? 0);
+  const endMinutes = (endH ?? 0) * 60 + (endM ?? 0);
+  if (startMinutes <= endMinutes) {
+    return currentMinutes >= startMinutes && currentMinutes < endMinutes;
+  }
+  return currentMinutes >= startMinutes || currentMinutes < endMinutes;
+}
+
+// src/heartbeat/worker.ts
+var HEARTBEAT_OK_TOKEN = "HEARTBEAT_OK";
+var HEARTBEAT_ROOM_KEY = "heartbeat:main";
+var HEARTBEAT_WORKER_NAME = "heartbeat";
+async function readHeartbeatFile(runtime, filename) {
+  const settings = runtime.character?.settings ?? {};
+  const workspace = typeof settings.workspace === "string" ? settings.workspace : process.cwd();
+  const filePath = path.resolve(workspace, filename);
+  const content = await fs.readFile(filePath, "utf-8").catch(() => null);
+  return content;
+}
+function buildHeartbeatPrompt(heartbeatMd, events) {
+  const parts = [];
+  parts.push("[Heartbeat]");
+  if (heartbeatMd) {
+    parts.push("");
+    parts.push("# HEARTBEAT.md");
+    parts.push(heartbeatMd.trim());
+    parts.push("");
+    parts.push("Follow the instructions in HEARTBEAT.md strictly.");
+  }
+  if (events.length > 0) {
+    parts.push("");
+    parts.push("## System events since last heartbeat");
+    for (const ev of events) {
+      const age = Math.round((Date.now() - ev.ts) / 1e3);
+      parts.push(`- [${ev.source}, ${age}s ago] ${ev.text}`);
+    }
+  }
+  parts.push("");
+  parts.push(
+    'If nothing requires your attention right now, reply with exactly "HEARTBEAT_OK" and nothing else.'
+  );
+  return parts.join("\n");
+}
+function isHeartbeatOk(text) {
+  const trimmed = text.trim();
+  return trimmed === HEARTBEAT_OK_TOKEN || trimmed.startsWith(`${HEARTBEAT_OK_TOKEN}
+`) || trimmed.startsWith(`${HEARTBEAT_OK_TOKEN} `);
+}
+async function ensureHeartbeatRoom(runtime) {
+  const roomId = stringToUuid(`${runtime.agentId}-${HEARTBEAT_ROOM_KEY}`);
+  const existing = await runtime.getRoom(roomId);
+  if (!existing) {
+    await runtime.createRoom({
+      id: roomId,
+      name: "Heartbeat",
+      source: "cron",
+      type: ChannelType.GROUP,
+      channelId: HEARTBEAT_ROOM_KEY
+    });
+    await runtime.addParticipant(runtime.agentId, roomId);
+  }
+  return roomId;
+}
+async function runHeartbeatTick(runtime, config) {
+  if (!isWithinActiveHours(config.activeHours)) {
+    logger2.debug("[Heartbeat] Outside active hours, skipping");
+    return;
+  }
+  const events = drainSystemEvents(runtime.agentId);
+  const heartbeatMd = await readHeartbeatFile(runtime, config.promptFile);
+  if (!heartbeatMd && events.length === 0) {
+    logger2.debug("[Heartbeat] No HEARTBEAT.md and no pending events, skipping");
+    return;
+  }
+  const promptText = buildHeartbeatPrompt(heartbeatMd, events);
+  const roomId = await ensureHeartbeatRoom(runtime);
+  const messageId = uuidv42();
+  const memory = {
+    id: messageId,
+    entityId: runtime.agentId,
+    roomId,
+    agentId: runtime.agentId,
+    content: { text: promptText },
+    createdAt: Date.now()
+  };
+  let responseText = "";
+  const callback = async (response) => {
+    if (response.text) {
+      responseText += response.text;
+    }
+    return [];
+  };
+  logger2.info(
+    `[Heartbeat] Running tick (${events.length} pending events, HEARTBEAT.md: ${heartbeatMd ? "yes" : "no"})`
+  );
+  if (!runtime.messageService) {
+    throw new Error("messageService is not available on runtime");
+  }
+  await runtime.messageService.handleMessage(runtime, memory, callback);
+  if (!responseText.trim() || isHeartbeatOk(responseText)) {
+    logger2.debug("[Heartbeat] Agent responded HEARTBEAT_OK, suppressing delivery");
+    return;
+  }
+  logger2.info(`[Heartbeat] Agent has something to say, delivering to target "${config.target}"`);
+  if (config.target === "none") {
+    return;
+  }
+  let channel;
+  let to;
+  if (config.target === "last" || config.target === "none") {
+    channel = config.target;
+  } else {
+    const colonIdx = config.target.indexOf(":");
+    if (colonIdx === -1) {
+      channel = config.target;
+    } else {
+      channel = config.target.slice(0, colonIdx);
+      to = config.target.slice(colonIdx + 1) || void 0;
+    }
+  }
+  if (channel === "none") {
+    return;
+  }
+  await deliverToTarget(
+    runtime,
+    { text: responseText },
+    channel,
+    to,
+    true
+    // bestEffort for heartbeat -- don't crash the tick on delivery failure
+  );
+}
+var heartbeatWorker = {
+  name: HEARTBEAT_WORKER_NAME,
+  async execute(runtime, _options, _task) {
+    const config = resolveHeartbeatConfig(runtime);
+    if (!config.enabled) {
+      return;
+    }
+    await runHeartbeatTick(runtime, config);
+  }
+};
+async function startHeartbeat(runtime) {
+  const config = resolveHeartbeatConfig(runtime);
+  if (!config.enabled) {
+    logger2.info("[Heartbeat] Disabled via config");
+    return;
+  }
+  runtime.registerTaskWorker(heartbeatWorker);
+  const existingTasks = await runtime.getTasks({
+    roomId: runtime.agentId,
+    tags: ["heartbeat", "queue", "repeat"]
+  });
+  const alreadyExists = existingTasks.some((t) => t.name === HEARTBEAT_WORKER_NAME);
+  if (!alreadyExists) {
+    await runtime.createTask({
+      name: HEARTBEAT_WORKER_NAME,
+      description: "Periodic agent heartbeat \u2013 reads HEARTBEAT.md and checks system events",
+      roomId: runtime.agentId,
+      tags: ["heartbeat", "queue", "repeat"],
+      metadata: {
+        updateInterval: config.everyMs,
+        updatedAt: Date.now(),
+        blocking: true
+      }
+    });
+    logger2.info(`[Heartbeat] Created recurring task (every ${Math.round(config.everyMs / 1e3)}s)`);
+  } else {
+    logger2.info("[Heartbeat] Recurring task already exists");
+  }
+}
+async function wakeHeartbeatNow(runtime) {
+  runtime.registerTaskWorker(heartbeatWorker);
+  await runtime.createTask({
+    name: HEARTBEAT_WORKER_NAME,
+    description: "Immediate heartbeat wake",
+    roomId: runtime.agentId,
+    tags: ["heartbeat", "queue"],
+    metadata: {
+      updatedAt: 0,
+      // ensures it runs immediately
+      blocking: false
+    }
+  });
+  logger2.info("[Heartbeat] Queued immediate wake");
+}
+
+// src/types.ts
+var DEFAULT_CRON_CONFIG = {
+  minIntervalMs: 1e4,
+  // 10 seconds minimum
+  maxJobsPerAgent: 100,
+  defaultTimeoutMs: 3e5,
+  // 5 minutes
+  catchUpMissedJobs: false,
+  catchUpWindowMs: 36e5,
+  // 1 hour
+  timerCheckIntervalMs: 1e3
+  // 1 second
+};
+
+// src/otto/executor.ts
+function withTimeout(promise, timeoutMs) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error("Job execution timeout")), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+async function executeSystemEvent(runtime, job, payload) {
+  const startedAtMs = Date.now();
+  pushSystemEvent(runtime.agentId, payload.text, `cron:${job.id}`);
+  logger3.info(`[Otto Executor] Queued system event for heartbeat: "${payload.text.slice(0, 80)}"`);
+  if (job.wakeMode === "now") {
+    await wakeHeartbeatNow(runtime);
+  }
+  return {
+    status: "ok",
+    durationMs: Date.now() - startedAtMs,
+    output: `System event queued (wake: ${job.wakeMode})`
+  };
+}
+async function ensureCronRoom(runtime, jobId, jobName) {
+  const roomKey = `cron:${jobId}`;
+  const roomId = stringToUuid2(`${runtime.agentId}-${roomKey}`);
+  const existing = await runtime.getRoom(roomId);
+  if (!existing) {
+    await runtime.createRoom({
+      id: roomId,
+      name: `Cron: ${jobName}`,
+      source: "cron",
+      type: ChannelType2.GROUP,
+      channelId: roomKey
+    });
+    await runtime.addParticipant(runtime.agentId, roomId);
+  }
+  return roomId;
+}
+async function executeAgentTurn(runtime, job, payload, config) {
+  const startedAtMs = Date.now();
+  const timeoutMs = payload.timeoutSeconds ? payload.timeoutSeconds * 1e3 : config.defaultTimeoutMs ?? DEFAULT_CRON_CONFIG.defaultTimeoutMs;
+  const roomId = await ensureCronRoom(runtime, job.id, job.name);
+  const promptPrefix = `[cron:${job.id} ${job.name}]`;
+  const messageText = `${promptPrefix} ${payload.message}`;
+  const messageId = uuidv43();
+  const memory = {
+    id: messageId,
+    entityId: runtime.agentId,
+    roomId,
+    agentId: runtime.agentId,
+    content: { text: messageText },
+    createdAt: Date.now()
+  };
+  let responseText = "";
+  const callback = async (response) => {
+    if (response.text) {
+      responseText += response.text;
+    }
+    return [];
+  };
+  let status = "ok";
+  let error;
+  if (!runtime.messageService) {
+    throw new Error("messageService is not available on runtime");
+  }
+  const runPromise = runtime.messageService.handleMessage(runtime, memory, callback);
+  await withTimeout(runPromise, timeoutMs).catch((err) => {
+    if (err.message === "Job execution timeout") {
+      status = "timeout";
+      error = "Execution timed out";
+    } else {
+      status = "error";
+      error = err.message;
+    }
+  });
+  const durationMs = Date.now() - startedAtMs;
+  if (status !== "ok") {
+    return { status, durationMs, error };
+  }
+  const plan = resolveCronDeliveryPlan(job);
+  if (plan.requested && responseText.trim() && responseText.trim() !== "HEARTBEAT_OK") {
+    logger3.info(
+      `[Otto Executor] Delivering response for "${job.name}" to ${plan.channel}${plan.to ? `:${plan.to}` : ""}`
+    );
+    const deliveryError = await deliverToTarget(
+      runtime,
+      { text: responseText },
+      plan.channel,
+      plan.to,
+      job.delivery?.bestEffort
+    ).then(
+      () => null,
+      (err) => err
+    );
+    if (deliveryError) {
+      return {
+        status: "error",
+        durationMs: Date.now() - startedAtMs,
+        output: responseText,
+        error: `Delivery failed: ${deliveryError.message}`
+      };
+    }
+  }
+  if (responseText.trim() && responseText.trim() !== "HEARTBEAT_OK") {
+    const summary = responseText.length > 200 ? `${responseText.slice(0, 200)}\u2026` : responseText;
+    pushSystemEvent(
+      runtime.agentId,
+      `[Cron "${job.name}" completed] ${summary}`,
+      `cron:${job.id}`
+    );
+    if (job.wakeMode === "now") {
+      await wakeHeartbeatNow(runtime);
+    }
+  }
+  return {
+    status: "ok",
+    durationMs,
+    output: responseText || void 0
+  };
+}
+async function executeOttoJob(runtime, job, config) {
+  const { payload } = job;
+  switch (payload.kind) {
+    case "systemEvent":
+      return executeSystemEvent(runtime, job, payload);
+    case "agentTurn":
+      return executeAgentTurn(runtime, job, payload, config);
+    default: {
+      const kind = payload.kind;
+      return {
+        status: "error",
+        durationMs: 0,
+        error: `Unknown Otto payload kind: ${kind}`
+      };
+    }
+  }
+}
+
+// src/otto/job-utils.ts
+function assertSupportedJobSpec(job) {
+  if (job.sessionTarget === "main" && job.payload.kind !== "systemEvent") {
+    throw new Error('main cron jobs require payload.kind="systemEvent"');
+  }
+  if (job.sessionTarget === "isolated" && job.payload.kind !== "agentTurn") {
+    throw new Error('isolated cron jobs require payload.kind="agentTurn"');
+  }
+}
+function assertDeliverySupport(job) {
+  if (job.delivery && job.sessionTarget !== "isolated") {
+    throw new Error('cron delivery config is only supported for sessionTarget="isolated"');
+  }
+}
+function normalizeRequiredName(name) {
+  const val = typeof name === "string" ? name.trim() : "";
+  if (!val) {
+    throw new Error("cron job name is required");
+  }
+  return val;
+}
+function normalizeOptionalText(text) {
+  if (typeof text !== "string") {
+    return void 0;
+  }
+  const trimmed = text.trim();
+  return trimmed || void 0;
+}
+function normalizeOptionalAgentId(agentId) {
+  if (typeof agentId !== "string") {
+    return void 0;
+  }
+  const trimmed = agentId.trim().toLowerCase();
+  return trimmed || void 0;
+}
+function applyJobPatch(job, patch) {
+  if ("name" in patch) {
+    job.name = normalizeRequiredName(patch.name);
+  }
+  if ("description" in patch) {
+    job.description = normalizeOptionalText(patch.description);
+  }
+  if (typeof patch.enabled === "boolean") {
+    job.enabled = patch.enabled;
+  }
+  if (typeof patch.deleteAfterRun === "boolean") {
+    job.deleteAfterRun = patch.deleteAfterRun;
+  }
+  if (patch.schedule) {
+    job.schedule = patch.schedule;
+  }
+  if (patch.sessionTarget) {
+    job.sessionTarget = patch.sessionTarget;
+  }
+  if (patch.wakeMode) {
+    job.wakeMode = patch.wakeMode;
+  }
+  if (patch.payload) {
+    job.payload = mergeCronPayload(job.payload, patch.payload);
+  }
+  if (!patch.delivery && patch.payload?.kind === "agentTurn") {
+    const legacyDeliveryPatch = buildLegacyDeliveryPatch(patch.payload);
+    if (legacyDeliveryPatch && job.sessionTarget === "isolated" && job.payload.kind === "agentTurn") {
+      job.delivery = mergeCronDelivery(job.delivery, legacyDeliveryPatch);
+    }
+  }
+  if (patch.delivery) {
+    job.delivery = mergeCronDelivery(job.delivery, patch.delivery);
+  }
+  if (job.sessionTarget === "main" && job.delivery) {
+    job.delivery = void 0;
+  }
+  if (patch.state) {
+    job.state = { ...job.state, ...patch.state };
+  }
+  if ("agentId" in patch) {
+    job.agentId = normalizeOptionalAgentId(patch.agentId);
+  }
+  assertSupportedJobSpec(job);
+  assertDeliverySupport(job);
+}
+function mergeCronPayload(existing, patch) {
+  if (patch.kind !== existing.kind) {
+    return buildPayloadFromPatch(patch);
+  }
+  if (patch.kind === "systemEvent") {
+    if (existing.kind !== "systemEvent") {
+      return buildPayloadFromPatch(patch);
+    }
+    const text = typeof patch.text === "string" ? patch.text : existing.text;
+    return { kind: "systemEvent", text };
+  }
+  if (existing.kind !== "agentTurn") {
+    return buildPayloadFromPatch(patch);
+  }
+  const next = { ...existing };
+  if (typeof patch.message === "string") {
+    next.message = patch.message;
+  }
+  if (typeof patch.model === "string") {
+    next.model = patch.model;
+  }
+  if (typeof patch.thinking === "string") {
+    next.thinking = patch.thinking;
+  }
+  if (typeof patch.timeoutSeconds === "number") {
+    next.timeoutSeconds = patch.timeoutSeconds;
+  }
+  if (typeof patch.deliver === "boolean") {
+    next.deliver = patch.deliver;
+  }
+  if (typeof patch.channel === "string") {
+    next.channel = patch.channel;
+  }
+  if (typeof patch.to === "string") {
+    next.to = patch.to;
+  }
+  if (typeof patch.bestEffortDeliver === "boolean") {
+    next.bestEffortDeliver = patch.bestEffortDeliver;
+  }
+  return next;
+}
+function buildLegacyDeliveryPatch(payload) {
+  const deliver = payload.deliver;
+  const toRaw = typeof payload.to === "string" ? payload.to.trim() : "";
+  const hasLegacyHints = typeof deliver === "boolean" || typeof payload.bestEffortDeliver === "boolean" || Boolean(toRaw);
+  if (!hasLegacyHints) {
+    return null;
+  }
+  const patch = {};
+  let hasPatch = false;
+  if (deliver === false) {
+    patch.mode = "none";
+    hasPatch = true;
+  } else if (deliver === true || toRaw) {
+    patch.mode = "announce";
+    hasPatch = true;
+  }
+  if (typeof payload.channel === "string") {
+    const channel = payload.channel.trim().toLowerCase();
+    patch.channel = channel ? channel : void 0;
+    hasPatch = true;
+  }
+  if (typeof payload.to === "string") {
+    patch.to = payload.to.trim();
+    hasPatch = true;
+  }
+  if (typeof payload.bestEffortDeliver === "boolean") {
+    patch.bestEffort = payload.bestEffortDeliver;
+    hasPatch = true;
+  }
+  return hasPatch ? patch : null;
+}
+function buildPayloadFromPatch(patch) {
+  if (patch.kind === "systemEvent") {
+    if (typeof patch.text !== "string" || patch.text.length === 0) {
+      throw new Error('cron.update payload.kind="systemEvent" requires text');
+    }
+    return { kind: "systemEvent", text: patch.text };
+  }
+  if (typeof patch.message !== "string" || patch.message.length === 0) {
+    throw new Error('cron.update payload.kind="agentTurn" requires message');
+  }
+  return {
+    kind: "agentTurn",
+    message: patch.message,
+    model: patch.model,
+    thinking: patch.thinking,
+    timeoutSeconds: patch.timeoutSeconds,
+    deliver: patch.deliver,
+    channel: patch.channel,
+    to: patch.to,
+    bestEffortDeliver: patch.bestEffortDeliver
+  };
+}
+function mergeCronDelivery(existing, patch) {
+  const next = {
+    mode: existing?.mode ?? "none",
+    channel: existing?.channel,
+    to: existing?.to,
+    bestEffort: existing?.bestEffort
+  };
+  if (typeof patch.mode === "string") {
+    next.mode = patch.mode === "deliver" ? "announce" : patch.mode;
+  }
+  if ("channel" in patch) {
+    const channel = typeof patch.channel === "string" ? patch.channel.trim() : "";
+    next.channel = channel ? channel : void 0;
+  }
+  if ("to" in patch) {
+    const to = typeof patch.to === "string" ? patch.to.trim() : "";
+    next.to = to ? to : void 0;
+  }
+  if (typeof patch.bestEffort === "boolean") {
+    next.bestEffort = patch.bestEffort;
+  }
+  return next;
+}
+
+// src/otto/parse.ts
+var ISO_TZ_RE = /(Z|[+-]\d{2}:?\d{2})$/i;
+var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var ISO_DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T/;
+function normalizeUtcIso(raw) {
+  if (ISO_TZ_RE.test(raw)) {
+    return raw;
+  }
+  if (ISO_DATE_RE.test(raw)) {
+    return `${raw}T00:00:00Z`;
+  }
+  if (ISO_DATE_TIME_RE.test(raw)) {
+    return `${raw}Z`;
+  }
+  return raw;
+}
+function parseAbsoluteTimeMs(input) {
+  const raw = input.trim();
+  if (!raw) {
+    return null;
+  }
+  if (/^\d+$/.test(raw)) {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) {
+      return Math.floor(n);
+    }
+  }
+  const parsed = Date.parse(normalizeUtcIso(raw));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// src/otto/payload-migration.ts
+function readString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  return value;
+}
+function normalizeChannel2(value) {
+  return value.trim().toLowerCase();
+}
+function migrateLegacyCronPayload(payload) {
+  let mutated = false;
+  const channelValue = readString(payload.channel);
+  const providerValue = readString(payload.provider);
+  const nextChannel = typeof channelValue === "string" && channelValue.trim().length > 0 ? normalizeChannel2(channelValue) : typeof providerValue === "string" && providerValue.trim().length > 0 ? normalizeChannel2(providerValue) : "";
+  if (nextChannel) {
+    if (channelValue !== nextChannel) {
+      payload.channel = nextChannel;
+      mutated = true;
+    }
+  }
+  if ("provider" in payload) {
+    delete payload.provider;
+    mutated = true;
+  }
+  return mutated;
+}
+
+// src/otto/normalize.ts
+var DEFAULT_OPTIONS = {
+  applyDefaults: false
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function coerceSchedule(schedule) {
+  const next = { ...schedule };
+  const kind = typeof schedule.kind === "string" ? schedule.kind : void 0;
+  const atMsRaw = schedule.atMs;
+  const atRaw = schedule.at;
+  const atString = typeof atRaw === "string" ? atRaw.trim() : "";
+  const parsedAtMs = typeof atMsRaw === "number" ? atMsRaw : typeof atMsRaw === "string" ? parseAbsoluteTimeMs(atMsRaw) : atString ? parseAbsoluteTimeMs(atString) : null;
+  if (!kind) {
+    if (typeof schedule.atMs === "number" || typeof schedule.at === "string" || typeof schedule.atMs === "string") {
+      next.kind = "at";
+    } else if (typeof schedule.everyMs === "number") {
+      next.kind = "every";
+    } else if (typeof schedule.expr === "string") {
+      next.kind = "cron";
+    }
+  }
+  if (atString) {
+    next.at = parsedAtMs ? new Date(parsedAtMs).toISOString() : atString;
+  } else if (parsedAtMs !== null) {
+    next.at = new Date(parsedAtMs).toISOString();
+  }
+  if ("atMs" in next) {
+    delete next.atMs;
+  }
+  return next;
+}
+function coercePayload(payload) {
+  const next = { ...payload };
+  migrateLegacyCronPayload(next);
+  return next;
+}
+function coerceDelivery(delivery) {
+  const next = { ...delivery };
+  if (typeof delivery.mode === "string") {
+    const mode = delivery.mode.trim().toLowerCase();
+    next.mode = mode === "deliver" ? "announce" : mode;
+  }
+  if (typeof delivery.channel === "string") {
+    const trimmed = delivery.channel.trim().toLowerCase();
+    if (trimmed) {
+      next.channel = trimmed;
+    } else {
+      delete next.channel;
+    }
+  }
+  if (typeof delivery.to === "string") {
+    const trimmed = delivery.to.trim();
+    if (trimmed) {
+      next.to = trimmed;
+    } else {
+      delete next.to;
+    }
+  }
+  return next;
+}
+function hasLegacyDeliveryHints(payload) {
+  if (typeof payload.deliver === "boolean") {
+    return true;
+  }
+  if (typeof payload.bestEffortDeliver === "boolean") {
+    return true;
+  }
+  if (typeof payload.to === "string" && payload.to.trim()) {
+    return true;
+  }
+  return false;
+}
+function buildDeliveryFromLegacyPayload(payload) {
+  const deliver = payload.deliver;
+  const mode = deliver === false ? "none" : "announce";
+  const channelRaw = typeof payload.channel === "string" ? payload.channel.trim().toLowerCase() : "";
+  const toRaw = typeof payload.to === "string" ? payload.to.trim() : "";
+  const next = { mode };
+  if (channelRaw) {
+    next.channel = channelRaw;
+  }
+  if (toRaw) {
+    next.to = toRaw;
+  }
+  if (typeof payload.bestEffortDeliver === "boolean") {
+    next.bestEffort = payload.bestEffortDeliver;
+  }
+  return next;
+}
+function stripLegacyDeliveryFields(payload) {
+  if ("deliver" in payload) {
+    delete payload.deliver;
+  }
+  if ("channel" in payload) {
+    delete payload.channel;
+  }
+  if ("to" in payload) {
+    delete payload.to;
+  }
+  if ("bestEffortDeliver" in payload) {
+    delete payload.bestEffortDeliver;
+  }
+}
+function unwrapJob(raw) {
+  if (isRecord(raw.data)) {
+    return raw.data;
+  }
+  if (isRecord(raw.job)) {
+    return raw.job;
+  }
+  return raw;
+}
+function defaultSanitizeAgentId(raw) {
+  return raw.trim().toLowerCase();
+}
+function normalizeCronJobInput(raw, options = DEFAULT_OPTIONS) {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  const base = unwrapJob(raw);
+  const next = { ...base };
+  const sanitizeAgentId = options.sanitizeAgentId ?? defaultSanitizeAgentId;
+  if ("agentId" in base) {
+    const agentId = base.agentId;
+    if (agentId === null) {
+      next.agentId = null;
+    } else if (typeof agentId === "string") {
+      const trimmed = agentId.trim();
+      if (trimmed) {
+        next.agentId = sanitizeAgentId(trimmed);
+      } else {
+        delete next.agentId;
+      }
+    }
+  }
+  if ("enabled" in base) {
+    const enabled = base.enabled;
+    if (typeof enabled === "boolean") {
+      next.enabled = enabled;
+    } else if (typeof enabled === "string") {
+      const trimmed = enabled.trim().toLowerCase();
+      if (trimmed === "true") {
+        next.enabled = true;
+      }
+      if (trimmed === "false") {
+        next.enabled = false;
+      }
+    }
+  }
+  if (isRecord(base.schedule)) {
+    next.schedule = coerceSchedule(base.schedule);
+  }
+  if (isRecord(base.payload)) {
+    next.payload = coercePayload(base.payload);
+  }
+  if (isRecord(base.delivery)) {
+    next.delivery = coerceDelivery(base.delivery);
+  }
+  if (isRecord(base.isolation)) {
+    delete next.isolation;
+  }
+  if (options.applyDefaults) {
+    if (!next.wakeMode) {
+      next.wakeMode = "next-heartbeat";
+    }
+    if (typeof next.enabled !== "boolean") {
+      next.enabled = true;
+    }
+    if (!next.sessionTarget && isRecord(next.payload)) {
+      const kind = typeof next.payload.kind === "string" ? next.payload.kind : "";
+      if (kind === "systemEvent") {
+        next.sessionTarget = "main";
+      }
+      if (kind === "agentTurn") {
+        next.sessionTarget = "isolated";
+      }
+    }
+    if ("schedule" in next && isRecord(next.schedule) && next.schedule.kind === "at" && !("deleteAfterRun" in next)) {
+      next.deleteAfterRun = true;
+    }
+    const payload = isRecord(next.payload) ? next.payload : null;
+    const payloadKind = payload && typeof payload.kind === "string" ? payload.kind : "";
+    const sessionTarget = typeof next.sessionTarget === "string" ? next.sessionTarget : "";
+    const isIsolatedAgentTurn = sessionTarget === "isolated" || sessionTarget === "" && payloadKind === "agentTurn";
+    const hasDelivery = "delivery" in next && next.delivery !== void 0;
+    const hasLegacyDelivery = payload ? hasLegacyDeliveryHints(payload) : false;
+    if (!hasDelivery && isIsolatedAgentTurn && payloadKind === "agentTurn") {
+      if (payload && hasLegacyDelivery) {
+        next.delivery = buildDeliveryFromLegacyPayload(payload);
+        stripLegacyDeliveryFields(payload);
+      } else {
+        next.delivery = { mode: "announce" };
+      }
+    }
+  }
+  return next;
+}
+function normalizeCronJobCreate(raw, options) {
+  return normalizeCronJobInput(raw, {
+    applyDefaults: true,
+    ...options
+  });
+}
+function normalizeCronJobPatch(raw, options) {
+  return normalizeCronJobInput(raw, {
+    applyDefaults: false,
+    ...options
+  });
+}
+
+// src/otto/run-log.ts
+import fs2 from "node:fs/promises";
+import path2 from "node:path";
+function resolveCronRunLogPath(params) {
+  const storePath = path2.resolve(params.storePath);
+  const dir = path2.dirname(storePath);
+  return path2.join(dir, "runs", `${params.jobId}.jsonl`);
+}
+var writesByPath = /* @__PURE__ */ new Map();
+async function pruneIfNeeded(filePath, opts) {
+  const stat = await fs2.stat(filePath).catch(() => null);
+  if (!stat || stat.size <= opts.maxBytes) {
+    return;
+  }
+  const raw = await fs2.readFile(filePath, "utf-8").catch(() => "");
+  const lines = raw.split("\n").map((l) => l.trim()).filter(Boolean);
+  const kept = lines.slice(Math.max(0, lines.length - opts.keepLines));
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+  await fs2.writeFile(tmp, `${kept.join("\n")}
+`, "utf-8");
+  await fs2.rename(tmp, filePath);
+}
+async function appendCronRunLog(filePath, entry, opts) {
+  const resolved = path2.resolve(filePath);
+  const prev = writesByPath.get(resolved) ?? Promise.resolve();
+  const next = prev.catch(() => void 0).then(async () => {
+    await fs2.mkdir(path2.dirname(resolved), { recursive: true });
+    await fs2.appendFile(resolved, `${JSON.stringify(entry)}
+`, "utf-8");
+    await pruneIfNeeded(resolved, {
+      maxBytes: opts?.maxBytes ?? 2e6,
+      keepLines: opts?.keepLines ?? 2e3
+    });
+  });
+  writesByPath.set(resolved, next);
+  await next;
+}
+async function readCronRunLogEntries(filePath, opts) {
+  const limit = Math.max(1, Math.min(5e3, Math.floor(opts?.limit ?? 200)));
+  const jobId = opts?.jobId?.trim() || void 0;
+  const raw = await fs2.readFile(path2.resolve(filePath), "utf-8").catch(() => "");
+  if (!raw.trim()) {
+    return [];
+  }
+  const parsed = [];
+  const lines = raw.split("\n");
+  for (let i = lines.length - 1; i >= 0 && parsed.length < limit; i--) {
+    const line = lines[i]?.trim();
+    if (!line) {
+      continue;
+    }
+    try {
+      const obj = JSON.parse(line);
+      if (!obj || typeof obj !== "object") {
+        continue;
+      }
+      if (obj.action !== "finished") {
+        continue;
+      }
+      if (typeof obj.jobId !== "string" || obj.jobId.trim().length === 0) {
+        continue;
+      }
+      if (typeof obj.ts !== "number" || !Number.isFinite(obj.ts)) {
+        continue;
+      }
+      if (jobId && obj.jobId !== jobId) {
+        continue;
+      }
+      parsed.push(obj);
+    } catch {
+    }
+  }
+  return [...parsed].reverse();
+}
+
+// src/otto/store.ts
+import fs3 from "node:fs";
+import os from "node:os";
+import path3 from "node:path";
+function resolveCronStorePath(storePath) {
+  if (storePath?.trim()) {
+    const raw = storePath.trim();
+    if (raw.startsWith("~")) {
+      return path3.resolve(raw.replace("~", os.homedir()));
+    }
+    return path3.resolve(raw);
+  }
+  return void 0;
+}
+async function loadCronStore(storePath) {
+  try {
+    const raw = await fs3.promises.readFile(storePath, "utf-8");
+    let parsed;
+    try {
+      const JSON5 = await import("./dist-KM2GC6Y3.js").then((m) => m.default);
+      parsed = JSON5.parse(raw);
+    } catch {
+      parsed = JSON.parse(raw);
+    }
+    const jobs = Array.isArray(parsed?.jobs) ? parsed?.jobs : [];
+    return {
+      version: 1,
+      jobs: jobs.filter(Boolean)
+    };
+  } catch {
+    return { version: 1, jobs: [] };
+  }
+}
+async function saveCronStore(storePath, store) {
+  await fs3.promises.mkdir(path3.dirname(storePath), { recursive: true });
+  const tmp = `${storePath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+  const json = JSON.stringify(store, null, 2);
+  await fs3.promises.writeFile(tmp, json, "utf-8");
+  await fs3.promises.rename(tmp, storePath);
+  try {
+    await fs3.promises.copyFile(storePath, `${storePath}.bak`);
+  } catch {
+  }
+}
+
+// src/otto/validate-timestamp.ts
+var ONE_MINUTE_MS = 60 * 1e3;
+var TEN_YEARS_MS = 10 * 365.25 * 24 * 60 * 60 * 1e3;
+function validateScheduleTimestamp(schedule, nowMs = Date.now()) {
+  if (schedule.kind !== "at") {
+    return { ok: true };
+  }
+  const atRaw = typeof schedule.at === "string" ? schedule.at.trim() : "";
+  const atMs = atRaw ? parseAbsoluteTimeMs(atRaw) : null;
+  if (atMs === null || !Number.isFinite(atMs)) {
+    return {
+      ok: false,
+      message: `Invalid schedule.at: expected ISO-8601 timestamp (got ${String(schedule.at)})`
+    };
+  }
+  const diffMs = atMs - nowMs;
+  if (diffMs < -ONE_MINUTE_MS) {
+    const nowDate = new Date(nowMs).toISOString();
+    const atDate = new Date(atMs).toISOString();
+    const minutesAgo = Math.floor(-diffMs / ONE_MINUTE_MS);
+    return {
+      ok: false,
+      message: `schedule.at is in the past: ${atDate} (${minutesAgo} minutes ago). Current time: ${nowDate}`
+    };
+  }
+  if (diffMs > TEN_YEARS_MS) {
+    const atDate = new Date(atMs).toISOString();
+    const yearsAhead = Math.floor(diffMs / (365.25 * 24 * 60 * 60 * 1e3));
+    return {
+      ok: false,
+      message: `schedule.at is too far in the future: ${atDate} (${yearsAhead} years ahead). Maximum allowed: 10 years`
+    };
+  }
+  return { ok: true };
+}
+
+export {
+  DEFAULT_CRON_CONFIG,
+  resolveHeartbeatConfig,
+  isWithinActiveHours,
+  pushSystemEvent,
+  drainSystemEvents,
+  pendingEventCount,
+  HEARTBEAT_WORKER_NAME,
+  heartbeatWorker,
+  startHeartbeat,
+  wakeHeartbeatNow,
+  resolveCronDeliveryPlan,
+  isOttoPayload,
+  executeOttoJob,
+  assertSupportedJobSpec,
+  assertDeliverySupport,
+  normalizeRequiredName,
+  normalizeOptionalText,
+  normalizeOptionalAgentId,
+  applyJobPatch,
+  parseAbsoluteTimeMs,
+  migrateLegacyCronPayload,
+  normalizeCronJobInput,
+  normalizeCronJobCreate,
+  normalizeCronJobPatch,
+  resolveCronRunLogPath,
+  appendCronRunLog,
+  readCronRunLogEntries,
+  resolveCronStorePath,
+  loadCronStore,
+  saveCronStore,
+  validateScheduleTimestamp,
+  otto_exports
+};