@saadnvd1/agent-os 0.3.479 → 0.3.482

package/lib/chat/test-touch.ts

@@ -1,17 +1,63 @@
-// For tests of file watching.
+// For tests that wait on async work or stand in for file watching.
+
+import fs from "fs";
+import { vi } from "vitest";
 
 export const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
-// Makes a change, and again every 2s until it's seen: macOS can be slow, and
-// drops an event while another watcher in the process opens or closes.
-// Returns how many times it changed things.
-export async function touchUntil(touch: () => void, seen: () => boolean) {
-  for (let n = 1; n <= 15; n++) {
-    touch();
-    for (let t = 0; t < 100; t++) {
-      if (seen()) return n;
-      await sleep(20);
-    }
+// Polls until `check` holds. The ceiling is generous: it only matters when
+// something is really broken, and a loaded machine never reaches it.
+export async function until(check: () => boolean, ceilingMs = 10_000) {
+  const end = Date.now() + ceilingMs;
+  while (!check()) {
+    if (Date.now() > end) throw new Error("condition never held");
+    await sleep(10);
   }
-  throw new Error("never seen");
+}
+
+export interface FakeWatch {
+  path: string;
+  recursive: boolean;
+  closed: boolean;
+  // Delivers an event as the OS would (null: no file name given).
+  fire(name: string | null): void;
+}
+
+// Replaces fs.watch with handles the test fires by hand: the OS's own events
+// arrive when it likes, which under load is never inside a test's wait.
+export function fakeFsWatch() {
+  const handles: FakeWatch[] = [];
+  const spy = vi.spyOn(fs, "watch").mockImplementation(((
+    p: unknown,
+    o: unknown,
+    listener: (e: string, name: string | null) => void
+  ) => {
+    const h: FakeWatch = {
+      path: String(p),
+      recursive: !!(o as { recursive?: boolean } | null)?.recursive,
+      closed: false,
+      fire: (name) => listener("rename", name),
+    };
+    handles.push(h);
+    return {
+      on() {},
+      close() {
+        h.closed = true;
+      },
+    };
+  }) as unknown as typeof fs.watch);
+  return {
+    all: handles,
+    open: () => handles.filter((h) => !h.closed),
+    // The live handle on `p`.
+    at(p: string, recursive?: boolean) {
+      return handles.find(
+        (h) =>
+          !h.closed &&
+          h.path === p &&
+          (recursive === undefined || h.recursive === recursive)
+      );
+    },
+    restore: () => spy.mockRestore(),
+  };
 }

package/lib/db/migrations.ts

@@ -1445,6 +1445,20 @@ const migrations: Migration[] = [
       );
     },
   },
+  {
+    id: 63,
+    name: "one_off_schedules",
+    up: (db) =>
+      db.transaction(() => {
+        // A one-off has a run time (epoch ms, UTC) and no cron; done_at is
+        // set once its single run settles. Recurring rows leave both NULL.
+        db.exec(`ALTER TABLE schedules ADD COLUMN run_at INTEGER`);
+        db.exec(`ALTER TABLE schedules ADD COLUMN done_at INTEGER`);
+        db.exec(
+          `CREATE INDEX IF NOT EXISTS idx_schedules_run_at ON schedules(run_at) WHERE run_at IS NOT NULL`
+        );
+      })(),
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/orchestrator/brief.ts

@@ -107,6 +107,9 @@ Acting:
 - \`${TOOL_NAMES.note}\` (text): a line in this workspace's decision log, shown in your chat. Note each decision that matters, with why.
 - \`${TOOL_NAMES.rule_add}\` (text): keep a standing rule for this workspace, in your brief on every start. Saad sees and edits them in Settings → Workspaces.
 - \`${TOOL_NAMES.rule_remove}\` (id): remove a standing rule you kept (Saad's are his to remove).
+- \`${TOOL_NAMES.remind_me}\` (at, prompt, name?): a one-off reminder to yourself ("tomorrow 10am", "in 2h"); it reaches you once as a scheduled prompt, not an approval, even if AgentOS was off. At least 10 minutes ahead. Prefer it to remembering to check back.
+- \`${TOOL_NAMES.reminders}\` (): your upcoming reminders and the last few that ran.
+- \`${TOOL_NAMES.cancel_reminder}\` (id): cancel a reminder you set.
 - \`${TOOL_NAMES.review}\` (target, fresh?): review a task's PR, or an external PR (#N, owner/repo#N or URL), at its head commit, or read the stored verdict.
 - \`${TOOL_NAMES.sign_off}\` (task): merge a task's PR or an external PR through the gates.
 - \`${TOOL_NAMES.arm}\` (task): merge a task's PR by itself the moment every gate passes; one event when it merges or a gate fails.

package/lib/orchestrator/reminders.ts

@@ -0,0 +1,91 @@
+/**
+ * remind_me, reminders and cancel_reminder: the orchestrator's one-off
+ * schedules. A reminder is a schedule that messages the workspace's own
+ * orchestrator once, so it arrives as a scheduled prompt and never as an
+ * approval. Every call is scoped to the caller's workspace, and only reminders
+ * an orchestrator made can be cancelled here: Saad's are his to change.
+ */
+
+import {
+  archiveSchedule,
+  createSchedule,
+  getSessionRow,
+  listSchedules,
+  type Schedule,
+} from "../schedules/store";
+import { reminderName } from "../schedules";
+import { DEFAULT_TIMEZONE, formatRunTime } from "../schedules/cron";
+import { parseWhen, relativeTime } from "../schedules/when";
+import { getOrchestrator } from "./home";
+import { addNote } from "./notes";
+
+const SHOW_DONE = 3;
+
+const line = (s: Schedule) =>
+  `${s.id.slice(0, 8)}  ${s.name}: ${formatRunTime(s.run_at ?? 0, s.timezone)} (${relativeTime(s.run_at ?? 0)})`;
+
+const madeByOrchestrator = (s: Schedule) =>
+  getSessionRow(s.created_by_session_id ?? "")?.role === "orchestrator";
+
+export function remindMe(
+  w: string,
+  at: string,
+  prompt: string,
+  name?: string
+): string {
+  const me = getOrchestrator(w);
+  if (!me) throw new Error("This workspace has no orchestrator");
+  const runAt = parseWhen(at, DEFAULT_TIMEZONE);
+  const schedule = createSchedule({
+    workspaceId: w,
+    name: name?.trim() || reminderName(w, runAt, DEFAULT_TIMEZONE),
+    at: runAt,
+    timezone: DEFAULT_TIMEZONE,
+    prompt,
+    kind: "orchestrator",
+    createdBySessionId: me.id,
+  });
+  addNote(
+    w,
+    `Reminder set: ${schedule.name}, ${line(schedule).split(": ")[1]}`
+  );
+  return `Reminder ${schedule.id.slice(0, 8)} set for ${formatRunTime(runAt, DEFAULT_TIMEZONE)} (${relativeTime(runAt)}). It reaches you as a scheduled prompt, not an approval.`;
+}
+
+export function listReminders(w: string): string {
+  const all = listSchedules(w).filter((s) => s.run_at != null);
+  const upcoming = all
+    .filter((s) => s.enabled && !s.done_at)
+    .sort((a, b) => (a.run_at ?? 0) - (b.run_at ?? 0));
+  const done = all
+    .filter((s) => s.done_at)
+    .sort((a, b) => (b.done_at ?? 0) - (a.done_at ?? 0))
+    .slice(0, SHOW_DONE);
+  if (!upcoming.length && !done.length) return "No reminders.";
+  return [
+    upcoming.length
+      ? `Upcoming:\n${upcoming.map(line).join("\n")}`
+      : "None upcoming.",
+    done.length
+      ? `Recently done:\n${done.map((s) => `${s.id.slice(0, 8)}  ${s.name}`).join("\n")}`
+      : "",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function cancelReminder(w: string, id: string): string {
+  const ref = id.trim();
+  const matches = listSchedules(w).filter(
+    (s) =>
+      s.run_at != null &&
+      !s.done_at &&
+      (s.id === ref || (ref.length >= 6 && s.id.startsWith(ref)))
+  );
+  // Another workspace's, a done one and one Saad made all read the same.
+  if (matches.length !== 1 || !madeByOrchestrator(matches[0]))
+    throw new Error(`No reminder "${ref}" in this workspace`);
+  archiveSchedule(matches[0].id);
+  addNote(w, `Reminder cancelled: ${matches[0].name}`);
+  return `Reminder ${matches[0].id.slice(0, 8)} cancelled.`;
+}

package/lib/orchestrator/serve.ts

@@ -28,6 +28,7 @@ import { land } from "./signoff";
 import { arm, disarm } from "./armed";
 import { quickChange, quickPR } from "./quick";
 import { review } from "./review";
+import { cancelReminder, listReminders, remindMe } from "./reminders";
 import { parseArgs as p, type ToolName } from "./tool-schemas";
 
 export { isToolName, TOOLS, type ToolName } from "./tool-schemas";
@@ -169,6 +170,14 @@ export async function runTool(
       addNote(w, `Removed standing rule ${rule.id}: ${rule.text}`);
       return `Rule ${rule.id} removed.`;
     }
+    case "remind_me": {
+      const a = p(tool, raw);
+      return remindMe(w, a.at, a.prompt, a.name);
+    }
+    case "reminders":
+      return listReminders(w);
+    case "cancel_reminder":
+      return cancelReminder(w, p(tool, raw).id);
     case "review": {
       const a = p(tool, raw);
       return reviewTarget(w, a.target, { fresh: a.fresh });

package/lib/orchestrator/tool-names.ts

@@ -32,6 +32,9 @@ export const TOOL_NAMES = {
   sign_off: name("sign_off"),
   arm: name("arm"),
   disarm: name("disarm"),
+  remind_me: name("remind_me"),
+  reminders: name("reminders"),
+  cancel_reminder: name("cancel_reminder"),
   ask_saad: name("ask_saad"),
 } as const;
 

package/lib/orchestrator/tool-schemas.ts

@@ -194,6 +194,23 @@ export const TOOL_SHAPES = {
       .describe("The rule, one sentence"),
   },
   rule_remove: { id: z.number().int().positive().describe("The rule's id") },
+  remind_me: {
+    at: z
+      .string()
+      .trim()
+      .min(1)
+      .max(100)
+      .describe('When: "tomorrow 10am", "in 2h" or 2026-10-12T10:00 (Central)'),
+    prompt: z
+      .string()
+      .trim()
+      .min(1)
+      .max(2000)
+      .describe("What to remind yourself of, in words you'll understand later"),
+    name: z.string().trim().min(1).max(80).optional(),
+  },
+  reminders: {},
+  cancel_reminder: { id: ref("The reminder's id, from reminders") },
   review: {
     target: ref("The task, or its PR (#12 or URL)"),
     fresh: z

package/lib/orchestrator/tools.ts

@@ -84,6 +84,12 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     'Keep a standing rule for this workspace, in your brief on every start from now on ("never merge #111", "briefs must not name third-party products"). It restricts or informs; it can never approve anything.',
   rule_remove:
     "Remove a standing rule you kept, by its id, only when Saad says so or it no longer applies (the PR it names merged or closed). Saad's rules are his to remove.",
+  remind_me:
+    "Set a one-off reminder for yourself in this workspace: at the time given it reaches you once as a scheduled prompt (not an approval), even if AgentOS was off then. At least 10 minutes ahead; a few at a time at most.",
+  reminders:
+    "List this workspace's upcoming reminders and the last few that ran.",
+  cancel_reminder:
+    "Cancel a reminder you set, by its id from reminders. Reminders Saad made are his to change.",
   review:
     "Start an independent read-only review of a PR at its exact head commit, or read the stored verdict for that commit. Takes a task, or any open PR in a workspace repository by #N, owner/repo#N or URL, even one no task owns.",
   sign_off:

package/lib/schedules/badge.ts

@@ -5,14 +5,24 @@ export interface SchedulesBadge {
   next: { name: string; at: number; timezone: string } | null;
   // How many schedules' last run failed.
   failed: number;
+  // Enabled one-offs still to run, soonest first.
+  upcoming: number;
+  nextUpcoming: { name: string; at: number; timezone: string } | null;
 }
 
 // What the sidebar's Schedules clock says at a glance.
 export function schedulesBadge(schedules: ScheduleView[]): SchedulesBadge {
   let next: SchedulesBadge["next"] = null;
   let failed = 0;
+  let upcoming = 0;
+  let nextUpcoming: SchedulesBadge["nextUpcoming"] = null;
   for (const s of schedules) {
     if (s.lastRun?.outcome === "failed") failed++;
+    if (s.oneOff && s.enabled && !s.done_at) {
+      upcoming++;
+      if (s.nextRunAt && (!nextUpcoming || s.nextRunAt < nextUpcoming.at))
+        nextUpcoming = { name: s.name, at: s.nextRunAt, timezone: s.timezone };
+    }
     if (
       s.enabled &&
       !s.paused &&
@@ -21,5 +31,5 @@ export function schedulesBadge(schedules: ScheduleView[]): SchedulesBadge {
     )
       next = { name: s.name, at: s.nextRunAt, timezone: s.timezone };
   }
-  return { next, failed };
+  return { next, failed, upcoming, nextUpcoming };
 }

package/lib/schedules/cron.ts

@@ -100,7 +100,7 @@ export function isTimezone(tz: string): boolean {
 }
 
 const formatters = new Map<string, Intl.DateTimeFormat>();
-function wall(ms: number, tz: string) {
+export function wall(ms: number, tz: string) {
   let f = formatters.get(tz);
   if (!f) {
     f = new Intl.DateTimeFormat("en-US", {

package/lib/schedules/index.ts

@@ -7,7 +7,13 @@
 
 import { getProject } from "../projects";
 import { resolveSession } from "../bus";
-import { describeCron, everyCron } from "./cron";
+import {
+  DEFAULT_TIMEZONE,
+  describeCron,
+  everyCron,
+  formatRunTime,
+} from "./cron";
+import { parseWhen } from "./when";
 import { runSlot, type RunDeps, type RunResult } from "./run";
 import { nextRunAt } from "./scheduler";
 import { realDeps } from "./start";
@@ -37,12 +43,28 @@ export interface ScheduleView extends Schedule {
   lastRun: ScheduleRun | null;
   // Its workspace's orchestrator is paused, so it skips its slots.
   paused: boolean;
+  oneOff: boolean;
+  // Who made it: Saad, or the agent session (the orchestrator, or another).
+  createdBy: { kind: "saad" | "orchestrator" | "session"; name: string };
+}
+
+function creatorOf(s: Schedule): ScheduleView["createdBy"] {
+  const creator = s.created_by_session_id
+    ? getSessionRow(s.created_by_session_id)
+    : null;
+  if (!creator) return { kind: "saad", name: "Saad" };
+  return creator.role === "orchestrator"
+    ? { kind: "orchestrator", name: "Orchestrator" }
+    : { kind: "session", name: creator.name };
 }
 
 export function scheduleView(s: Schedule, now = Date.now()): ScheduleView {
   return {
     ...s,
-    description: describeCron(s.cron),
+    description:
+      s.run_at != null
+        ? `Once, ${formatRunTime(s.run_at, s.timezone)}`
+        : describeCron(s.cron),
     projectName: s.project_id ? (getProject(s.project_id)?.name ?? null) : null,
     targetName: s.target_session_id
       ? (getSessionRow(s.target_session_id)?.name ?? null)
@@ -50,6 +72,8 @@ export function scheduleView(s: Schedule, now = Date.now()): ScheduleView {
     nextRunAt: nextRunAt(s, now),
     lastRun: lastRun(s.id),
     paused: isPaused(s.workspace_id),
+    oneOff: s.run_at != null,
+    createdBy: creatorOf(s),
   };
 }
 
@@ -65,6 +89,8 @@ export function checkInInput(opts: {
   from?: string | null;
   every?: string;
   cron?: string;
+  // A one-off instead of a cron: "tomorrow 10am", "in 2h", an ISO time.
+  at?: string;
   prompt: string;
   name?: string;
   timezone?: string;
@@ -79,14 +105,26 @@ export function checkInInput(opts: {
     if (sessionWorkspace(creator) !== workspaceId)
       throw new Error(`${session.name} isn't in your workspace`);
   }
-  const cron = opts.cron?.trim() || everyCron(opts.every ?? "30m");
+  if (opts.at && (opts.cron || opts.every))
+    throw new Error("Give a run time (at) or a repeat (every, cron), not both");
+  const tz = opts.timezone?.trim() || DEFAULT_TIMEZONE;
+  const runAt = opts.at ? parseWhen(opts.at, tz) : null;
+  const cron =
+    runAt === null
+      ? opts.cron?.trim() || everyCron(opts.every ?? "30m")
+      : undefined;
   // The workspace's orchestrator is kept as "its orchestrator", not this
   // session's id: each run goes to whichever session is orchestrator then.
   const orchestrator = session.role === "orchestrator";
   return {
     workspaceId,
-    name: opts.name?.trim() || `Check-in: ${session.name}`.slice(0, 80),
+    name:
+      opts.name?.trim() ||
+      (runAt === null
+        ? `Check-in: ${session.name}`.slice(0, 80)
+        : reminderName(workspaceId, runAt, tz)),
     cron,
+    at: runAt,
     timezone: opts.timezone,
     prompt: opts.prompt,
     kind: orchestrator ? "orchestrator" : "message",
@@ -95,12 +133,30 @@ export function checkInInput(opts: {
   };
 }
 
+// "Reminder Tue, Oct 7, 9:00 AM", with a number after it when that's taken.
+export function reminderName(
+  workspaceId: string,
+  runAt: number,
+  tz = DEFAULT_TIMEZONE
+): string {
+  const taken = new Set(
+    listSchedules(workspaceId)
+      .filter((s) => !s.done_at)
+      .map((s) => s.name.toLowerCase())
+  );
+  const base = `Reminder ${formatRunTime(runAt, tz)}`;
+  let name = base;
+  for (let n = 2; taken.has(name.toLowerCase()); n++) name = `${base} (${n})`;
+  return name;
+}
+
 export function scheduleHistory(id: string, limit = 50): ScheduleRun[] {
   return listRuns(id, limit);
 }
 
 // Run now: its own slot, whatever the time and while the last run is still
-// working. Pause holds it like any run.
+// working. Pause holds it like any run. A one-off has one slot, so Run now
+// uses up its only run.
 export async function runNow(
   id: string,
   deps: RunDeps = realDeps
@@ -108,6 +164,11 @@ export async function runNow(
   const schedule = getSchedule(id);
   if (!schedule || schedule.archived_at) throw new Error("Schedule not found");
   const result = await runSlot(schedule, Date.now(), "manual", deps);
-  if (!result) throw new Error("Couldn't claim a run");
+  if (!result)
+    throw new Error(
+      schedule.run_at != null
+        ? "It already ran: edit it to a new time to run it again"
+        : "Couldn't claim a run"
+    );
   return result;
 }

package/lib/schedules/run.ts

@@ -3,6 +3,7 @@ import {
   attachSession,
   brakeRun,
   claimSlot,
+  finishOneOff,
   finishRun,
   lastSettledBefore,
   lastStarted,
@@ -60,8 +61,15 @@ export async function runSlot(
   trigger: RunTrigger,
   deps: RunDeps
 ): Promise<RunResult | null> {
+  // A one-off has one slot, Run now included: the claim is what stops it
+  // running twice.
+  const oneOff = schedule.run_at != null;
+  if (oneOff) slotAt = schedule.run_at!;
   const slot =
-    trigger === "manual" ? `manual:${randomUUID()}` : slotKey(slotAt);
+    trigger === "manual" && !oneOff
+      ? `manual:${randomUUID()}`
+      : slotKey(slotAt);
+  if (oneOff && schedule.done_at) return null;
   const runId = claimSlot(schedule.id, slot, slotAt, trigger);
   if (runId === null) return null;
   const caughtUp = trigger === "catch-up" ? "caught up" : null;
@@ -71,6 +79,7 @@ export async function runSlot(
     sessionId: string | null = null
   ): RunResult => {
     finishRun(runId, outcome, detail, sessionId);
+    if (oneOff) finishOneOff(schedule.id);
     return { runId, outcome, detail, sessionId };
   };
   const joined = (...parts: (string | null)[]) =>
@@ -90,6 +99,16 @@ export async function runSlot(
     return done("failed", why);
   };
 
+  // A recurring run skips while paused; a one-off has only this run, so it's
+  // held like a brake and runs once the workspace resumes.
+  const paused = (): RunResult => {
+    if (!oneOff)
+      return done("skipped", joined(caughtUp, "paused with the orchestrator"));
+    const detail = "held: paused with the orchestrator";
+    brakeRun(runId, detail);
+    return { runId, outcome: "skipped", detail, sessionId: null };
+  };
+
   // Its session is gone and won't come back: the schedule turns itself off
   // and says so once, instead of failing every slot.
   const gone = targetGone(schedule);
@@ -100,9 +119,8 @@ export async function runSlot(
   }
   const target = targetProblem(schedule);
   if (target) return fail(target);
-  if (pausedFor(schedule))
-    return done("skipped", joined(caughtUp, "paused with the orchestrator"));
-  if (trigger !== "manual") {
+  if (pausedFor(schedule)) return paused();
+  if (trigger !== "manual" && !oneOff) {
     const previous = lastStarted(schedule.id, runId);
     if (previous) {
       let busy: boolean;
@@ -128,8 +146,7 @@ export async function runSlot(
   }
 
   // Again: Saad may have paused while the overlap check waited.
-  if (pausedFor(schedule))
-    return done("skipped", joined(caughtUp, "paused with the orchestrator"));
+  if (pausedFor(schedule)) return paused();
   try {
     const started = await deps.start(schedule, (id) =>
       attachSession(runId, id)

package/lib/schedules/scheduler.ts

@@ -23,14 +23,24 @@ export const LATE_MS = 90 * 1000;
 
 // The slot a schedule is due to run now, if any.
 export function dueSlot(schedule: Schedule, now: number): number | null {
-  if (!schedule.enabled || schedule.archived_at) return null;
+  if (!schedule.enabled || schedule.archived_at || schedule.done_at)
+    return null;
+  // A one-off is due from its run time on, whenever AgentOS notices: no
+  // armed_at cut-off, so a run missed while it was off still happens.
+  if (schedule.run_at != null) {
+    if (schedule.run_at > now) return null;
+    return slotTaken(schedule.id, slotKey(schedule.run_at))
+      ? null
+      : schedule.run_at;
+  }
   const slot = prevRun(schedule.cron, now, schedule.timezone);
   if (slot === null || slot <= schedule.armed_at) return null;
   return slotTaken(schedule.id, slotKey(slot)) ? null : slot;
 }
 
 export function nextRunAt(schedule: Schedule, now = Date.now()): number | null {
-  if (!schedule.enabled) return null;
+  if (!schedule.enabled || schedule.done_at) return null;
+  if (schedule.run_at != null) return schedule.run_at;
   return nextRun(
     schedule.cron,
     Math.max(now, schedule.armed_at),

package/lib/schedules/start.ts

@@ -85,15 +85,21 @@ async function startSession(
 // Marked as a schedule's, not something Saad just typed: the orchestrator's
 // brief says it never counts as an approval.
 export function scheduledMessage(
-  schedule: Pick<Schedule, "name" | "prompt">,
+  schedule: Pick<Schedule, "name" | "prompt"> & { run_at?: number | null },
   projectName: string | null,
   // An agent set it up: it's that agent's request, not Saad's.
-  creator?: Pick<Session, "id" | "name"> | null
+  creator?: (Pick<Session, "id" | "name"> & { role?: string | null }) | null
 ): string {
   const where = projectName ? ` for ${projectName}` : "";
-  const who = creator
-    ? `, set up by agent session "${creator.name}" (${creator.id.slice(0, 8)}), not by the user: a peer's request, not an approval`
-    : ", saved in Schedules: a standing prompt, not an approval";
+  const once = schedule.run_at != null;
+  const who =
+    creator?.role === "orchestrator" && once
+      ? ", a reminder you set yourself with remind_me: your own follow-up, not an approval"
+      : creator
+        ? `, set up by agent session "${creator.name}" (${creator.id.slice(0, 8)}), not by the user: a peer's request, not an approval`
+        : once
+          ? ", a one-off reminder saved in Schedules: a prompt, not an approval"
+          : ", saved in Schedules: a standing prompt, not an approval";
   return `[Scheduled message "${schedule.name}"${where}${who}]\n${schedule.prompt}`;
 }