@saadnvd1/agent-os 0.3.479 → 0.3.482

package/lib/schedules/store.ts

@@ -10,7 +10,14 @@ import {
   MESSAGE_MIN_GAP_MINUTES,
   MIN_GAP_MINUTES,
   minGapMinutes,
+  formatRunTime,
 } from "./cron";
+import { parseWhen } from "./when";
+
+// Agents can't aim a reminder at themselves sooner than this (a reminder
+// loop), keep more than this many waiting, or set one past a year out.
+export const MAX_AGENT_REMINDERS = 20;
+const MAX_AHEAD_MS = 366 * 86_400_000;
 
 export const SCHEDULE_KINDS = [
   "task",
@@ -29,6 +36,7 @@ export interface Schedule {
   workspace_id: string;
   project_id: string | null;
   name: string;
+  // '' for a one-off (the column is NOT NULL).
   cron: string;
   timezone: string;
   prompt: string;
@@ -41,6 +49,10 @@ export interface Schedule {
   enabled: boolean;
   // Epoch ms: only slots after this run (set on create, enable, cron edit).
   armed_at: number;
+  // A one-off's single run time (epoch ms, UTC), or null when recurring.
+  run_at: number | null;
+  // Set when a one-off's run settled; it's off from then on.
+  done_at: number | null;
   archived_at: string | null;
   created_at: string;
   updated_at: string;
@@ -63,7 +75,10 @@ export interface ScheduleInput {
   workspaceId: string;
   projectId?: string | null;
   name: string;
-  cron: string;
+  // A cron, or `at` for a one-off: exactly one.
+  cron?: string;
+  // A one-off's time: text parseWhen reads (in `timezone`), or epoch ms.
+  at?: string | number | null;
   timezone?: string;
   prompt: string;
   kind: ScheduleKind;
@@ -93,6 +108,30 @@ export function listSchedules(workspaceId?: string | null): Schedule[] {
   return rows.map(toSchedule);
 }
 
+export const isOneOff = (s: Pick<Schedule, "run_at">): boolean =>
+  s.run_at != null;
+
+// One-offs still waiting to run, soonest first.
+export function upcomingOneOffs(workspaceId?: string | null): Schedule[] {
+  return listSchedules(workspaceId)
+    .filter((s) => isOneOff(s) && s.enabled && !s.done_at)
+    .sort((a, b) => a.run_at! - b.run_at!);
+}
+
+// Turns a one-off off once its run settled. True only for the call that did.
+const byOrchestrator = (sessionId: string | null | undefined) =>
+  !!sessionId && getSessionRow(sessionId)?.role === "orchestrator";
+
+export function finishOneOff(id: string, now = Date.now()): boolean {
+  return (
+    db
+      .prepare(
+        `UPDATE schedules SET enabled = 0, done_at = ?, updated_at = datetime('now') WHERE id = ? AND done_at IS NULL`
+      )
+      .run(now, id).changes === 1
+  );
+}
+
 export function getSchedule(id: string): Schedule | null {
   const row = db.prepare(`SELECT * FROM schedules WHERE id = ?`).get(id) as
     | Row
@@ -164,10 +203,18 @@ export function sessionTargetProblem(
   return null;
 }
 
+type Valid = Required<
+  Omit<ScheduleInput, "createdBySessionId" | "cron" | "at">
+> & { cron: string; runAt: number | null };
+
+// `keepPast`: a run time already accepted, allowed to stay once it has passed
+// (renaming a done one-off).
 function validate(
   input: ScheduleInput,
-  selfId?: string
-): Required<Omit<ScheduleInput, "createdBySessionId">> {
+  selfId?: string,
+  now = Date.now(),
+  keepPast: number | null = null
+): Valid {
   const name = input.name?.trim();
   if (!name) throw new Error("Give the schedule a name");
   if (name.length > 80) throw new Error("Keep the name under 80 characters");
@@ -178,11 +225,50 @@ function validate(
   if (!prompt) throw new Error("Write the prompt it runs");
   if (!SCHEDULE_KINDS.includes(input.kind))
     throw new Error("Pick task, session, orchestrator or message");
-  const cron = input.cron?.trim().replace(/\s+/g, " ");
-  const bad = cronError(cron ?? "");
-  if (bad) throw new Error(bad);
   const timezone = input.timezone?.trim() || DEFAULT_TIMEZONE;
   if (!isTimezone(timezone)) throw new Error(`Unknown time zone "${timezone}"`);
+  const cronText = input.cron?.trim().replace(/\s+/g, " ") ?? "";
+  const oneOff = input.at != null && input.at !== "";
+  if (oneOff && cronText)
+    throw new Error("Give a cron or a run time, not both");
+  if (!oneOff && !cronText) throw new Error("Needs a cron or a run time");
+  const runAt = oneOff
+    ? typeof input.at === "number"
+      ? input.at
+      : parseWhen(input.at as string, timezone, now)
+    : null;
+  if (runAt !== null) {
+    if (!Number.isFinite(runAt)) throw new Error("Pick a run time");
+    if (runAt <= now && runAt !== keepPast)
+      throw new Error(
+        `That time has passed (${formatRunTime(runAt, timezone)}): pick a time ahead`
+      );
+    if (runAt - now > MAX_AHEAD_MS)
+      throw new Error("A one-off can be at most a year ahead");
+    if (
+      input.createdBySessionId &&
+      runAt !== keepPast &&
+      runAt - now < MESSAGE_MIN_GAP_MINUTES * 60_000
+    )
+      throw new Error(
+        `A reminder must be at least ${MESSAGE_MIN_GAP_MINUTES} minutes ahead`
+      );
+    // The cap is on the orchestrator's remind_me reminders; a session's own
+    // `aos schedule add --at` isn't counted.
+    if (
+      !selfId &&
+      byOrchestrator(input.createdBySessionId) &&
+      upcomingOneOffs(input.workspaceId).filter((s) =>
+        byOrchestrator(s.created_by_session_id)
+      ).length >= MAX_AGENT_REMINDERS
+    )
+      throw new Error(
+        `At most ${MAX_AGENT_REMINDERS} reminders can wait at once: cancel one first`
+      );
+  }
+  const cron = cronText;
+  const bad = oneOff ? null : cronError(cron);
+  if (bad) throw new Error(bad);
   if (!getWorkspace(input.workspaceId)) throw new Error("Pick a workspace");
   const message = input.kind === "message";
   // A message goes to a session, whatever project it's in.
@@ -208,6 +294,7 @@ function validate(
     throw new Error("A task or session schedule needs a project");
   }
   if (
+    !oneOff &&
     (input.kind === "task" || input.kind === "session") &&
     minGapMinutes(cron, timezone) < MIN_GAP_MINUTES
   )
@@ -218,6 +305,7 @@ function validate(
   const agentCheckIn =
     input.kind === "orchestrator" && !!input.createdBySessionId;
   if (
+    !oneOff &&
     (message || agentCheckIn) &&
     minGapMinutes(cron, timezone) < MESSAGE_MIN_GAP_MINUTES
   )
@@ -225,7 +313,10 @@ function validate(
       `A message schedule runs at most every ${MESSAGE_MIN_GAP_MINUTES} minutes`
     );
   const clash = listSchedules(input.workspaceId).find(
-    (s) => s.id !== selfId && s.name.toLowerCase() === name.toLowerCase()
+    (s) =>
+      s.id !== selfId &&
+      !s.done_at &&
+      s.name.toLowerCase() === name.toLowerCase()
   );
   if (clash)
     throw new Error(`There's already a schedule called "${clash.name}"`);
@@ -239,6 +330,7 @@ function validate(
     kind: input.kind,
     targetSessionId,
     enabled: input.enabled ?? true,
+    runAt,
   };
 }
 
@@ -246,11 +338,11 @@ export function createSchedule(
   input: ScheduleInput,
   now = Date.now()
 ): Schedule {
-  const v = validate(input);
+  const v = validate(input, undefined, now);
   const id = randomUUID();
   db.prepare(
-    `INSERT INTO schedules (id, workspace_id, project_id, name, cron, timezone, prompt, kind, target_session_id, created_by_session_id, enabled, armed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    `INSERT INTO schedules (id, workspace_id, project_id, name, cron, timezone, prompt, kind, target_session_id, created_by_session_id, enabled, armed_at, run_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
   ).run(
     id,
     v.workspaceId,
@@ -263,7 +355,8 @@ export function createSchedule(
     v.targetSessionId,
     input.createdBySessionId ?? null,
     v.enabled ? 1 : 0,
-    now
+    now,
+    v.runAt
   );
   return getSchedule(id)!;
 }
@@ -281,7 +374,11 @@ export function updateSchedule(
       projectId:
         patch.projectId === undefined ? current.project_id : patch.projectId,
       name: patch.name ?? current.name,
-      cron: patch.cron ?? current.cron,
+      // A patch with a cron makes it recurring; one with `at`, a one-off.
+      cron:
+        patch.cron ??
+        (patch.at != null ? undefined : current.cron || undefined),
+      at: patch.at ?? (patch.cron != null ? null : current.run_at),
       timezone: patch.timezone ?? current.timezone,
       prompt: patch.prompt ?? current.prompt,
       kind: patch.kind ?? current.kind,
@@ -292,17 +389,27 @@ export function updateSchedule(
       enabled: patch.enabled ?? current.enabled,
       createdBySessionId: current.created_by_session_id,
     },
-    id
+    id,
+    now,
+    current.done_at || current.enabled ? current.run_at : null
   );
+  // A one-off moved to a new time opens again, even if it had run.
+  const reopen = v.runAt !== null && v.runAt !== current.run_at;
+  const enabled = reopen
+    ? (patch.enabled ?? true)
+    : v.runAt !== null && current.done_at
+      ? false
+      : v.enabled;
   // A new time or a fresh enable starts counting from now: no slot from
   // before it is "missed".
   const rearm =
     v.cron !== current.cron ||
+    v.runAt !== current.run_at ||
     v.timezone !== current.timezone ||
-    (v.enabled && !current.enabled);
+    (enabled && !current.enabled);
   db.prepare(
     `UPDATE schedules SET workspace_id = ?, project_id = ?, name = ?, cron = ?, timezone = ?,
-       prompt = ?, kind = ?, target_session_id = ?, enabled = ?, armed_at = ?, updated_at = datetime('now')
+       prompt = ?, kind = ?, target_session_id = ?, enabled = ?, armed_at = ?, run_at = ?, done_at = ?, updated_at = datetime('now')
      WHERE id = ?`
   ).run(
     v.workspaceId,
@@ -313,8 +420,10 @@ export function updateSchedule(
     v.prompt,
     v.kind,
     v.targetSessionId,
-    v.enabled ? 1 : 0,
+    enabled ? 1 : 0,
     rearm ? now : current.armed_at,
+    v.runAt,
+    reopen || v.runAt === null ? null : current.done_at,
     id
   );
   return getSchedule(id)!;
@@ -546,6 +655,14 @@ export function failAbandonedClaims(
   now = Date.now()
 ): number {
   const before = Math.floor((now - olderThanMs) / 1000);
+  // A one-off whose only run was cut off won't come round again: finish it
+  // here so it leaves Upcoming and stops counting toward the reminder cap.
+  db.prepare(
+    `UPDATE schedules SET enabled = 0, done_at = ?, updated_at = datetime('now')
+     WHERE run_at IS NOT NULL AND done_at IS NULL AND id IN (
+       SELECT schedule_id FROM schedule_runs
+       WHERE outcome = 'claimed' AND created_at < datetime(?, 'unixepoch'))`
+  ).run(now, before);
   const started = db
     .prepare(
       `UPDATE schedule_runs SET outcome = 'started', detail = 'AgentOS restarted while it was starting'

package/lib/schedules/when.ts

@@ -0,0 +1,166 @@
+// One parser for "when" so the API, the CLI and the orchestrator's remind_me
+// all read a time the same way: an ISO timestamp, "tomorrow 10am", "in 2h".
+
+import { DEFAULT_TIMEZONE, wall, wallToInstant } from "./cron";
+
+const DAYS = [
+  "sunday",
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+];
+const dayIndex = (word: string): number =>
+  DAYS.findIndex((d) => d === word || d.slice(0, 3) === word);
+
+const bad = (text: string) =>
+  new Error(
+    `Can't read "${text}" as a time: try "tomorrow 10am", "in 2h" or 2026-10-12T10:00`
+  );
+
+const UNIT_MS: Record<string, number> = {
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+function duration(text: string): number | null {
+  let total = 0;
+  const rest = text.replace(
+    /(\d+(?:\.\d+)?|an?)\s*(minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/g,
+    (_, n: string, unit: string) => {
+      total += (/^an?$/.test(n) ? 1 : Number(n)) * UNIT_MS[unit[0]];
+      return "";
+    }
+  );
+  return total > 0 && /^(\s|,|and)*$/.test(rest) ? total : null;
+}
+
+function clock(text: string): { h: number; mi: number } | null {
+  if (text === "noon") return { h: 12, mi: 0 };
+  if (text === "midnight") return { h: 0, mi: 0 };
+  const m = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/.exec(text);
+  if (!m) return null;
+  const mi = m[2] ? Number(m[2]) : 0;
+  let h = Number(m[1]);
+  if (mi > 59) return null;
+  if (m[3]) {
+    if (h < 1 || h > 12) return null;
+    h = (h % 12) + (m[3] === "pm" ? 12 : 0);
+  } else if (!m[2] || h > 23) {
+    // "tomorrow 10" is ambiguous; 24-hour times need their minutes.
+    return null;
+  }
+  return { h, mi };
+}
+
+const CLOCK = String.raw`noon|midnight|\d{1,2}(?::\d{2})?\s*(?:am|pm)?`;
+const DAY = String.raw`(?:next\s+)?(?:today|tomorrow|tmrw|[a-z]{3,9})`;
+const DAY_FIRST = new RegExp(`^(${DAY})\\s+(?:at\\s+)?(${CLOCK})$`);
+const CLOCK_FIRST = new RegExp(`^(?:at\\s+)?(${CLOCK})(?:\\s+(${DAY}))?$`);
+
+function onDay(
+  word: string | undefined,
+  at: { h: number; mi: number },
+  now: number,
+  tz: string
+): number | null {
+  const today = wall(now, tz);
+  const instantIn = (days: number) => {
+    const d = new Date(Date.UTC(today.y, today.m - 1, today.d + days));
+    return wallToInstant(
+      d.getUTCFullYear(),
+      d.getUTCMonth() + 1,
+      d.getUTCDate(),
+      at.h,
+      at.mi,
+      tz
+    );
+  };
+  const w = word?.replace(/^next\s+/, "");
+  if (!w) return instantIn(0) > now ? instantIn(0) : instantIn(1);
+  if (w === "today") return instantIn(0);
+  if (w === "tomorrow" || w === "tmrw") return instantIn(1);
+  const dow = dayIndex(w);
+  if (dow < 0) return null;
+  const todayDow = new Date(
+    Date.UTC(today.y, today.m - 1, today.d)
+  ).getUTCDay();
+  const delta = (dow - todayDow + 7) % 7;
+  return delta === 0 && instantIn(0) <= now ? instantIn(7) : instantIn(delta);
+}
+
+// The instant (epoch ms) the text names. An offset or Z is absolute; any other
+// wall time reads in `tz`; "in 2h" is an exact duration from `now`.
+export function parseWhen(
+  text: string,
+  tz = DEFAULT_TIMEZONE,
+  now = Date.now()
+): number {
+  const t = text.trim().toLowerCase().replace(/\s+/g, " ");
+  if (!t) throw bad(text);
+
+  const abs =
+    /^(\d{4}-\d{2}-\d{2})[t ](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)(z|[+-]\d{2}:?\d{2})$/.exec(
+      t
+    );
+  if (abs) {
+    const zone = abs[3] === "z" ? "Z" : abs[3].replace(/^([+-]\d{2}):?/, "$1:");
+    const ms = Date.parse(`${abs[1]}T${abs[2]}${zone}`);
+    if (Number.isNaN(ms)) throw bad(text);
+    return ms;
+  }
+
+  const iso =
+    /^(\d{4})-(\d{2})-(\d{2})(?:[t ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?)?$/.exec(
+      t
+    );
+  if (iso) {
+    const [y, m, d] = [Number(iso[1]), Number(iso[2]), Number(iso[3])];
+    const h = iso[4] === undefined ? 9 : Number(iso[4]);
+    const mi = iso[5] === undefined ? 0 : Number(iso[5]);
+    const check = new Date(Date.UTC(y, m - 1, d));
+    if (
+      check.getUTCMonth() !== m - 1 ||
+      check.getUTCDate() !== d ||
+      h > 23 ||
+      mi > 59
+    )
+      throw bad(text);
+    return wallToInstant(y, m, d, h, mi, tz);
+  }
+
+  const inside = /^in (.+)$/.exec(t);
+  if (inside) {
+    const ms = duration(inside[1]);
+    if (ms === null) throw bad(text);
+    return now + ms;
+  }
+
+  const first = DAY_FIRST.exec(t);
+  const second = first ? null : CLOCK_FIRST.exec(t);
+  const at = clock(first?.[2] ?? second?.[1] ?? "");
+  if (at) {
+    const instant = onDay(first?.[1] ?? second?.[2], at, now, tz);
+    if (instant !== null) return instant;
+  }
+  throw bad(text);
+}
+
+// "in 17h", "in 5m", "3h ago".
+export function relativeTime(ms: number, now = Date.now()): string {
+  const diff = ms - now;
+  const mins = Math.floor(Math.abs(diff) / 60_000);
+  const span =
+    mins < 1
+      ? null
+      : mins < 60
+        ? `${mins}m`
+        : mins < 24 * 60
+          ? `${Math.floor(mins / 60)}h`
+          : `${Math.floor(mins / (24 * 60))}d`;
+  if (!span) return diff >= 0 ? "in under a minute" : "just now";
+  return diff >= 0 ? `in ${span}` : `${span} ago`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.479",
+  "version": "0.3.482",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"
@@ -83,7 +83,6 @@
     "@codemirror/language": "^6.12.3",
     "@codemirror/state": "^6.6.0",
     "@codemirror/view": "^6.41.0",
-    "@legendapp/list": "3.3.11",
     "@lezer/highlight": "^1.2.3",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@monaco-editor/react": "^4.7.0",