@awebai/oats 0.27.2 → 0.28.0

package/lib/schedule.mjs

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
 import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
+import { tickTriggers } from "./triggers.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
@@ -65,6 +66,7 @@ const CAPTURED_SCHEDULE_REMOVED = "captured schedules are refused (the captured/
 export const HARNESS_CONFLICT = "harness and runtime (its pre-0.27 name) disagree: keep harness: and remove runtime:";
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
+  if (def.kind === "trigger") return "a trigger is managed by oats trigger, not oats schedule";
   if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
   if (typeof def.cron !== "string" || typeof def.tz !== "string") return "cron and tz must be strings";
   if (def.kind === "spawn" && typeof def.agent !== "string") return "agent must be a string";
@@ -246,7 +248,7 @@ export function withHostLock(fn, { retryMs = 0 } = {}) { return withDirLock(join
 /** Registry read-modify-write is serialized on its own short lock. */
 function withRegistryLock(fn) { return withDirLock(join(hostScheduleDir(), "registry.lock"), "the host schedule registry", fn, { retryMs: 3000 }); }
 /** Definitions and state are read-modify-write; CRUD serializes here briefly. */
-function withScopeLock(ws, fn) { return withDirLock(join(stateDir(ws), "scope.lock"), `schedules of ${ws}`, fn, { retryMs: 3000 }); }
+export function withScopeLock(ws, fn) { return withDirLock(join(stateDir(ws), "scope.lock"), `schedules of ${ws}`, fn, { retryMs: 3000 }); }
 
 export function acquireJobLock(ws, id, owner) {
   const dir = lockDir(ws, id);
@@ -288,6 +290,7 @@ function validateMessage(message, field) {
 /** Validate and normalize one definition against its scope. */
 export function validateDefinition(ws, def, { checkAgent = true } = {}) {
   if (!def || typeof def !== "object" || Array.isArray(def)) throw scheduleError("E_SCHEDULE_INVALID", "definition must be an object", { field: "definition" });
+  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_INVALID", "kind: a trigger is added with `oats trigger add`, not `oats schedule add`", { field: "kind" });
   const id = def.id;
   if (typeof id !== "string" || !ID_RE.test(id)) throw scheduleError("E_SCHEDULE_INVALID", "id: lowercase letters, digits and dashes, 1 to 40 characters", { field: "id" });
   const enabled = def.enabled === undefined ? true : def.enabled;
@@ -431,13 +434,13 @@ function scheduleBlock(def, minute) {
  *  may be invoked from inside an unrelated instance; dispatch belongs to the
  *  job's cwd and explicit selectors, never to that caller), host configuration
  *  such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
-function childEnv() {
+export function childEnv() {
   const env = { ...process.env };
   for (const key of [...RESERVED_LAUNCH_ENV,
     "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
     "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
     "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
-    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
+    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE", "OATS_TRIGGER_EVENT_FILE",
   ]) delete env[key];
   return env;
 }
@@ -671,6 +674,8 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   // are gone), then decide launches: a job ordered earlier must not see a
   // slot still held by a home that has already ended.
   // `candidates` (the host tick) means the host already observed every scope.
+  // Triggers (kind "trigger") live in the same file and are evaluated by tickTriggers, not here.
+  for (const [id, def] of Object.entries(defs.jobs)) if (def && def.kind === "trigger") delete defs.jobs[id];
   if (!candidates) for (const [id, def] of Object.entries(defs.jobs)) observePrevious(ws, id, def, stateOf(id), io, now, { mutate: !dryRun });
   if (observeOnly) { if (!dryRun) writeState(ws, st); return considered; }
   // Least recently LAUNCHED first: only an actual harness launch counts, a
@@ -778,7 +783,7 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
       try {
         considered.push(...tickWorkspace(ws, { now, io, reg, wsList, dryRun, observeOnly: true }));
         const defs = readDefinitions(ws), st = readState(ws);
-        for (const id of Object.keys(defs.jobs)) jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
+        for (const [id, def] of Object.entries(defs.jobs)) if (def?.kind !== "trigger") jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
       } catch (e) { considered.push({ workspace: ws, action: "error", error: e.message }); }
     }
     jobs.sort((a, b) => a.key.localeCompare(b.key) || a.ws.localeCompare(b.ws) || a.id.localeCompare(b.id));
@@ -786,6 +791,11 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
       try { considered.push(...tickWorkspace(j.ws, { now, io, reg, wsList, dryRun, candidates: [j.id] })); }
       catch (e) { considered.push({ workspace: j.ws, id: j.id, action: "error", error: e.message }); }
     }
+    // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
+    for (const ws of wsList) {
+      try { considered.push(...tickTriggers(ws, { now, io, dryRun })); }
+      catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
+    }
     if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
     return { tickedAt: now.toISOString(), minute: minuteKey(minuteStart(now)), considered, scheduler: schedulerStatus(undefined, io) };
   };
@@ -797,7 +807,7 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
 export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
   const defs = readDefinitions(ws);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def || def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
   if (!def.enabled && !force) throw scheduleError("E_SCHEDULE_DISABLED", `schedule ${id} is disabled; enable it or pass --force`);
   const reg = readRegistry();
   const wsList = reg.workspaces.includes(resolve(ws)) ? reg.workspaces : [...reg.workspaces, resolve(ws)];
@@ -824,7 +834,7 @@ export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
 export function reconcile(ws, id, { io, now = new Date(), clear = false } = {}) {
   const defs = readDefinitions(ws);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def || def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
   return withHostLock(() => {
     const st = readState(ws);
     const js = st.jobs[id] || (st.jobs[id] = {});
@@ -898,6 +908,7 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
   defs ||= readDefinitions(ws); st ||= readState(ws);
   const def = defs.jobs[id];
   if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `${id} is a trigger, not a schedule — use oats trigger show ${id}`);
   // Subject truth: the definition's own id must be the key it is stored under.
   if (def.id !== undefined && def.id !== id) throw scheduleError("E_SCHEDULE_IDENTITY", `schedule stored under ${JSON.stringify(id)} declares id ${JSON.stringify(def.id)}`, { key: id, declared: def.id });
   const js = st.jobs[id] || {};
@@ -910,11 +921,13 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
 export function listSchedules(ws, io, { now = new Date() } = {}) {
   const defs = readDefinitions(ws), st = readState(ws);
   // One job's bad identity or history does not fail the others: it is reported as its own row.
-  const schedules = Object.keys(defs.jobs).sort().map((id) => {
+  const schedules = Object.keys(defs.jobs).filter((id) => defs.jobs[id]?.kind !== "trigger").sort().map((id) => {
     try { return describe(ws, id, io, { defs, st, now }); }
     catch (e) { return { id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, unreadable: { code: e.code || "E_SCHEDULE_INVALID", message: e.message }, history: { status: "corrupt", stored: null, truncated: false }, recentRuns: [] }; }
   });
-  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), schedules, scheduler: schedulerStatus(ws, io) };
+  // Triggers share the definitions file but not this listing: a pointer, so they are never invisible.
+  const triggers = Object.values(defs.jobs).filter((d) => d?.kind === "trigger").length;
+  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), schedules, triggers: { count: triggers, command: "oats trigger list" }, scheduler: schedulerStatus(ws, io) };
 }
 export function addSchedule(ws, spec, io) {
   const def = validateDefinition(ws, spec);
@@ -935,7 +948,7 @@ export function updateSchedule(ws, id, spec, io) {
   const def = validateDefinition(ws, { ...spec, id });
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation, d.definitionVersion, d.recurrencePolicy, d.execution, d.preparation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
     if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its execution identity, kind, target and captured policy cannot change until it ends (cron, tz and enabled can)`);
@@ -947,7 +960,7 @@ export function updateSchedule(ws, id, spec, io) {
 export function setEnabled(ws, id, enabled, io) {
   return withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     defs.jobs[id] = { ...defs.jobs[id], enabled, updatedAt: new Date().toISOString() };
     writeDefinitions(ws, defs);
     return describe(ws, id, io);
@@ -958,7 +971,7 @@ export function setEnabled(ws, id, enabled, io) {
 export function removeSchedule(ws, id, { force = false } = {}) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     const st = readState(ws), job = st.jobs[id];
     if ((jobLockInfo(ws, id) || job?.attempt || job?.lastRun?.outcome === "unknown") && !force) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has unresolved effects; reconcile first, or --force forgets the job without stopping anything`);
     delete defs.jobs[id];