@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/schedule/scheduler.ts

@@ -1,9 +1,11 @@
+import { refreshBackgroundWakeIntent } from "../background-wake/publisher.js";
 import { getConfig } from "../config/loader.js";
 import {
   checkDiskPressureBackgroundGate,
   diskPressureBackgroundSkipLogFields,
   shouldLogDiskPressureBackgroundSkip,
 } from "../daemon/disk-pressure-background-gate.js";
+import { processMessage } from "../daemon/process-message.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../daemon/trust-context.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import { bootstrapConversation } from "../persistence/conversation-bootstrap.js";
@@ -16,7 +18,7 @@ import { publishConversationListChanged } from "../runtime/sync/resource-sync-ev
 import { runSequencesOnce } from "../sequence/engine.js";
 import { areCoreToolsInitialized } from "../tools/registry.js";
 import { getLogger } from "../util/logger.js";
-import { runWatchersOnce, type WatcherNotifier } from "../watcher/engine.js";
+import { runWatchersOnce } from "../watcher/engine.js";
 import { normalizeCapabilityManifest } from "../workflows/capabilities.js";
 import { getWorkflowRunManager } from "../workflows/run-manager.js";
 import { hasSetConstructs } from "./recurrence-engine.js";
@@ -38,28 +40,48 @@ import {
   scheduleRetry,
   setScheduleRunConversationId,
 } from "./schedule-store.js";
+import {
+  startScheduleWorkerIfEnabled,
+  stopScheduleWorker,
+} from "./worker-control.js";
 
 const log = getLogger("scheduler");
 
-import type { ScheduleMessageProcessor } from "./scheduler-types.js";
-type ScheduleNotifyModeNotifier = (payload: {
-  id: string;
-  label: string;
-  message: string;
-  routingIntent: RoutingIntent;
-  routingHints: Record<string, unknown>;
-}) => void | Promise<void>;
-
-type ScheduleConversationCreatedNotifier = (info: {
-  conversationId: string;
-  scheduleJobId: string;
-  title: string;
-}) => void;
+import type { ScheduleMessageOptions } from "./scheduler-types.js";
 
 /**
- * Emit the attention signal for a `notify`-mode schedule firing. The default
- * `notifyScheduleOneShot` for {@link startScheduler}; tests inject a stub.
+ * Run a scheduled message through the daemon's agent pipeline, translating the
+ * schedule's `trustClass` into the trust context `processMessage` expects.
  */
+async function dispatchScheduleMessage(
+  conversationId: string,
+  message: string,
+  options?: ScheduleMessageOptions,
+): Promise<void> {
+  await processMessage(
+    conversationId,
+    message,
+    options
+      ? {
+          ...(options.trustClass
+            ? {
+                trustContext: {
+                  sourceChannel: "vellum",
+                  trustClass: options.trustClass,
+                },
+              }
+            : {}),
+          ...(options.taskRunId ? { taskRunId: options.taskRunId } : {}),
+          ...(options.overrideProfile
+            ? { overrideProfile: options.overrideProfile }
+            : {}),
+          ...(options.cronRunId ? { cronRunId: options.cronRunId } : {}),
+        }
+      : undefined,
+  );
+}
+
+/** Emit the attention signal for a `notify`-mode schedule firing. */
 async function emitScheduleNotifySignal(payload: {
   id: string;
   label: string;
@@ -198,40 +220,23 @@ async function handleExecutionFailure(params: {
 /** The running scheduler, retained so shutdown can stop it. */
 let instance: SchedulerHandle | null = null;
 
-/**
- * Publish the current background wake intent without statically importing the
- * publisher — `background-wake/next-wake.js` imports the schedule store, so a
- * static import here would close an import cycle. Best-effort and fire-and-forget.
- */
-function refreshBackgroundWakeIntentSoon(reason: string): void {
-  void import("../background-wake/publisher.js")
-    .then(({ refreshBackgroundWakeIntent }) =>
-      refreshBackgroundWakeIntent(reason),
-    )
-    .catch((err) =>
-      log.warn({ err, reason }, "Failed to queue background wake refresh"),
-    );
-}
+export function startScheduler(): SchedulerHandle {
+  // When the schedule worker owns schedule execution, spawn it now as a child
+  // of the daemon so it is running immediately. Fire-and-forget — a worker
+  // failure must never block boot, and every tick below re-reads the flag so
+  // ownership stays consistent either way.
+  startScheduleWorkerIfEnabled();
 
-export function startScheduler(
-  processMessage: ScheduleMessageProcessor,
-  notifyScheduleOneShot: ScheduleNotifyModeNotifier = emitScheduleNotifySignal,
-  watcherNotifier: WatcherNotifier = emitWatcherNotifySignal,
-  onScheduleConversationCreated: ScheduleConversationCreatedNotifier = broadcastScheduleConversationCreated,
-): SchedulerHandle {
   let stopped = false;
   let tickRunning = false;
 
   const tick = async () => {
-    if (stopped || tickRunning) return;
+    if (stopped || tickRunning) {
+      return;
+    }
     tickRunning = true;
     try {
-      await runScheduleOnce(
-        processMessage,
-        notifyScheduleOneShot,
-        watcherNotifier,
-        onScheduleConversationCreated,
-      );
+      await runScheduleOnce();
     } catch (err) {
       log.error({ err }, "Schedule tick failed");
     } finally {
@@ -247,23 +252,12 @@ export function startScheduler(
 
   instance = {
     async runOnce(): Promise<number> {
-      return runScheduleOnce(
-        processMessage,
-        notifyScheduleOneShot,
-        watcherNotifier,
-        onScheduleConversationCreated,
-      );
+      return runScheduleOnce();
     },
     async runDueWorkOnce(
       options?: SchedulerRunDueWorkOptions,
     ): Promise<SchedulerDueWorkResult> {
-      return runScheduleDueWorkOnce(
-        processMessage,
-        notifyScheduleOneShot,
-        watcherNotifier,
-        onScheduleConversationCreated,
-        options,
-      );
+      return runScheduleDueWorkOnce(options);
     },
     stop(): void {
       stopped = true;
@@ -273,14 +267,22 @@ export function startScheduler(
 
   // Publish the initial background wake intent now that the scheduler is live
   // and its schedules are visible to `computeNextBackgroundWakeIntent`.
-  refreshBackgroundWakeIntentSoon("daemon-startup");
+  refreshBackgroundWakeIntent("daemon-startup");
 
   return instance;
 }
 
-/** Stop the running scheduler if one was started; no-op otherwise. */
+/**
+ * Stop the running scheduler if one was started, and SIGTERM the schedule
+ * worker process if one is running. The worker stop is keyed off live state
+ * rather than config: it may have been spawned at startup or out of band via
+ * `assistant schedules worker start`.
+ */
 export function stopScheduler(): void {
-  if (!instance) return;
+  stopScheduleWorker();
+  if (!instance) {
+    return;
+  }
   instance.stop();
   instance = null;
 }
@@ -290,30 +292,36 @@ export function getScheduler(): SchedulerHandle | null {
   return instance;
 }
 
-export async function runScheduleOnce(
-  processMessage: ScheduleMessageProcessor,
-  notifyScheduleOneShot: ScheduleNotifyModeNotifier,
-  watcherNotifier?: WatcherNotifier,
-  onScheduleConversationCreated?: ScheduleConversationCreatedNotifier,
-): Promise<number> {
-  const result = await runScheduleDueWorkOnce(
-    processMessage,
-    notifyScheduleOneShot,
-    watcherNotifier,
-    onScheduleConversationCreated,
-  );
+export async function runScheduleOnce(): Promise<number> {
+  const result = await runScheduleDueWorkOnce();
   return result.completed + result.failed + result.skipped;
 }
 
+/**
+ * True while the schedule worker process owns schedule execution. Read from
+ * config on every call so a runtime `assistant schedules worker start`/`stop`
+ * switches ownership without a restart.
+ */
+function scheduleWorkerOwnsSchedules(): boolean {
+  return getConfig().schedules?.worker?.enabled === true;
+}
+
 export async function runScheduleDueWorkOnce(
-  processMessage: ScheduleMessageProcessor,
-  notifyScheduleOneShot: ScheduleNotifyModeNotifier,
-  watcherNotifier?: WatcherNotifier,
-  onScheduleConversationCreated?: ScheduleConversationCreatedNotifier,
   options: SchedulerRunDueWorkOptions = {},
 ): Promise<SchedulerDueWorkResult> {
   const now = options.now ?? Date.now();
   const minStartBudgetMs = options.minStartBudgetMs ?? 0;
+  // While `schedules.worker.enabled` is set, the schedule worker process owns
+  // schedule execution: this process leaves every due schedule unclaimed so
+  // exactly one process runs them, and reports none of them as its own
+  // pending work. The flag is re-read from config every tick, so `assistant
+  // schedules worker start`/`stop` switch ownership without a restart.
+  // Watchers and sequences below always run in the daemon.
+  const workerOwnsSchedules = scheduleWorkerOwnsSchedules();
+  const countStillPending = (at: number): number =>
+    options.includeStillPending && !workerOwnsSchedules
+      ? countDueScheduleJobs(at)
+      : 0;
   const result: SchedulerDueWorkResult = {
     claimed: 0,
     completed: 0,
@@ -321,17 +329,12 @@ export async function runScheduleDueWorkOnce(
     skipped: 0,
     stillPending: 0,
   };
-  const mark = (status: "completed" | "failed" | "skipped") => {
-    result[status] += 1;
-  };
 
   if (
     options.deadlineAt != null &&
     options.deadlineAt - Date.now() < minStartBudgetMs
   ) {
-    result.stillPending = options.includeStillPending
-      ? countDueScheduleJobs(now)
-      : 0;
+    result.stillPending = countStillPending(now);
     result.skipped = result.stillPending;
     return result;
   }
@@ -347,13 +350,73 @@ export async function runScheduleDueWorkOnce(
         "Schedule tick skipped during disk pressure cleanup mode",
       );
     }
-    result.stillPending = options.includeStillPending
-      ? countDueScheduleJobs(now)
-      : 0;
+    result.stillPending = countStillPending(now);
     return result;
   }
 
   // ── Schedules (recurring cron/RRULE + one-shot) ─────────────────────
+  if (!workerOwnsSchedules) {
+    const schedules = await runDueSchedulesOnce(now);
+    result.claimed = schedules.claimed;
+    result.completed += schedules.completed;
+    result.failed += schedules.failed;
+    result.skipped += schedules.skipped;
+  }
+
+  // ── Watchers (event-driven polling) ────────────────────────────────
+  try {
+    const watcherProcessed = await runWatchersOnce(emitWatcherNotifySignal);
+    result.completed += watcherProcessed;
+  } catch (err) {
+    log.error({ err }, "Watcher tick failed");
+  }
+
+  // ── Sequences (multi-step outreach) ──────────────────────────────
+  try {
+    const sequenceProcessed = await runSequencesOnce();
+    result.completed += sequenceProcessed;
+  } catch (err) {
+    log.error({ err }, "Sequence engine tick failed");
+  }
+
+  result.stillPending = countStillPending(Date.now());
+  const processed = result.completed + result.failed + result.skipped;
+  if (processed > 0) {
+    log.info({ processed }, "Schedule tick complete");
+  }
+  return result;
+}
+
+/**
+ * Claim and execute every due schedule (all modes: notify, script, wake,
+ * workflow, execute). Called from the daemon's tick while
+ * `schedules.worker.enabled` is off, and from the schedule worker process's
+ * tick while it is on. Claims are atomic in the schedule store, so a process
+ * whose view of the flag lags a tick behind cannot double-run a job another
+ * process already claimed.
+ */
+export async function runDueSchedulesOnce(
+  now: number = Date.now(),
+): Promise<Omit<SchedulerDueWorkResult, "stillPending">> {
+  const result = { claimed: 0, completed: 0, failed: 0, skipped: 0 };
+  const mark = (status: "completed" | "failed" | "skipped") => {
+    result[status] += 1;
+  };
+
+  const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
+  if (diskPressureGate.action === "skip") {
+    if (shouldLogDiskPressureBackgroundSkip("scheduler-schedules")) {
+      log.warn(
+        {
+          source: "schedule",
+          ...diskPressureBackgroundSkipLogFields(diskPressureGate),
+        },
+        "Due-schedule run skipped during disk pressure cleanup mode",
+      );
+    }
+    return result;
+  }
+
   const jobs = await claimDueSchedules(now);
   result.claimed = jobs.length;
   for (const job of jobs) {
@@ -367,7 +430,7 @@ export async function runScheduleDueWorkOnce(
           { jobId: job.id, name: job.name, isOneShot },
           "Firing schedule notification",
         );
-        await notifyScheduleOneShot({
+        await emitScheduleNotifySignal({
           id: job.id,
           label: job.name,
           message: job.message,
@@ -428,6 +491,7 @@ export async function runScheduleDueWorkOnce(
         const result: ScriptResult = await runScript(job.script, {
           timeoutMs: job.timeoutMs ?? undefined,
           scheduleRunId: runId,
+          scheduleId: job.id,
         });
         await completeScheduleRun(runId, {
           status: result.exitCode === 0 ? "ok" : "error",
@@ -435,7 +499,9 @@ export async function runScheduleDueWorkOnce(
           error: result.stderr || undefined,
         });
         if (result.exitCode === 0) {
-          if (isOneShot) await completeOneShot(job.id);
+          if (isOneShot) {
+            await completeOneShot(job.id);
+          }
         } else {
           const errorMsg =
             result.stderr || "Script exited with non-zero status";
@@ -464,7 +530,9 @@ export async function runScheduleDueWorkOnce(
           { jobId: job.id, name: job.name },
           "Wake schedule missing wakeConversationId — completing as no-op",
         );
-        if (isOneShot) await completeOneShot(job.id);
+        if (isOneShot) {
+          await completeOneShot(job.id);
+        }
         mark("skipped");
         continue;
       }
@@ -528,7 +596,9 @@ export async function runScheduleDueWorkOnce(
             },
             "Wake not invoked; skipping feed event",
           );
-          if (isOneShot) await completeOneShot(job.id);
+          if (isOneShot) {
+            await completeOneShot(job.id);
+          }
           mark("skipped");
           continue;
         }
@@ -626,7 +696,9 @@ export async function runScheduleDueWorkOnce(
           status: "ok",
           output: `workflow run ${workflowRunId} started`,
         });
-        if (isOneShot) await completeOneShot(job.id);
+        if (isOneShot) {
+          await completeOneShot(job.id);
+        }
       } catch (err) {
         const errorMsg = err instanceof Error ? err.message : String(err);
         log.warn(
@@ -675,7 +747,7 @@ export async function runScheduleDueWorkOnce(
             scheduleJobId: job.id,
           },
           async (conversationId, message, taskRunId) => {
-            await processMessage(conversationId, message, {
+            await dispatchScheduleMessage(conversationId, message, {
               trustClass: "guardian",
               taskRunId,
               cronRunId: runId,
@@ -687,7 +759,7 @@ export async function runScheduleDueWorkOnce(
         );
 
         await setScheduleRunConversationId(runId, result.conversationId);
-        onScheduleConversationCreated?.({
+        broadcastScheduleConversationCreated({
           conversationId: result.conversationId,
           scheduleJobId: job.id,
           title: result.status === "failed" ? `${job.name}: Error` : job.name,
@@ -712,7 +784,9 @@ export async function runScheduleDueWorkOnce(
           failed = true;
         } else {
           await completeScheduleRun(runId, { status: "ok" });
-          if (isOneShot) await completeOneShot(job.id);
+          if (isOneShot) {
+            await completeOneShot(job.id);
+          }
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -738,7 +812,7 @@ export async function runScheduleDueWorkOnce(
           origin: "schedule",
           systemHint: `Schedule: ${job.name}`,
         });
-        onScheduleConversationCreated?.({
+        broadcastScheduleConversationCreated({
           conversationId: fallbackConversation.id,
           scheduleJobId: job.id,
           title: `${job.name}: Error`,
@@ -801,18 +875,18 @@ export async function runScheduleDueWorkOnce(
     const runId = await createScheduleRun(job.id, reusedConversationId);
 
     if (reusedConversationId) {
-      // Reuse path: keep using the injected `processMessage` callback so the
-      // existing conversation is continued in place. `runBackgroundJob`
-      // unconditionally bootstraps a new conversation and is therefore not a
-      // drop-in replacement for the reuse semantics.
+      // Reuse path: dispatch the message into the existing conversation so it
+      // is continued in place. `runBackgroundJob` unconditionally bootstraps a
+      // new conversation and is therefore not a drop-in replacement for the
+      // reuse semantics.
       conversationId = reusedConversationId;
-      onScheduleConversationCreated?.({
+      broadcastScheduleConversationCreated({
         conversationId,
         scheduleJobId: job.id,
         title: job.name,
       });
       try {
-        await processMessage(conversationId, job.message, {
+        await dispatchScheduleMessage(conversationId, job.message, {
           trustClass: "guardian",
           cronRunId: runId,
           ...(job.inferenceProfile
@@ -854,7 +928,7 @@ export async function runScheduleDueWorkOnce(
         onConversationCreated: async (newConversationId) => {
           runConversationId = newConversationId;
           await setScheduleRunConversationId(runId, newConversationId);
-          onScheduleConversationCreated?.({
+          broadcastScheduleConversationCreated({
             conversationId: newConversationId,
             scheduleJobId: job.id,
             title: job.name,
@@ -880,7 +954,9 @@ export async function runScheduleDueWorkOnce(
 
     if (ok) {
       await completeScheduleRun(runId, { status: "ok" });
-      if (isOneShot) await completeOneShot(job.id);
+      if (isOneShot) {
+        await completeOneShot(job.id);
+      }
       mark("completed");
     } else {
       log.warn(
@@ -923,31 +999,6 @@ export async function runScheduleDueWorkOnce(
     }
   }
 
-  // ── Watchers (event-driven polling) ────────────────────────────────
-  if (watcherNotifier) {
-    try {
-      const watcherProcessed = await runWatchersOnce(watcherNotifier);
-      result.completed += watcherProcessed;
-    } catch (err) {
-      log.error({ err }, "Watcher tick failed");
-    }
-  }
-
-  // ── Sequences (multi-step outreach) ──────────────────────────────
-  try {
-    const sequenceProcessed = await runSequencesOnce();
-    result.completed += sequenceProcessed;
-  } catch (err) {
-    log.error({ err }, "Sequence engine tick failed");
-  }
-
-  if (options.includeStillPending) {
-    result.stillPending = countDueScheduleJobs(Date.now());
-  }
-  const processed = result.completed + result.failed + result.skipped;
-  if (processed > 0) {
-    log.info({ processed }, "Schedule tick complete");
-  }
   return result;
 }
 

package/src/schedule/worker-control.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared control surface for the schedule worker *process* — the background OS
+ * process whose entry point is `worker.ts`.
+ *
+ * Both the `assistant schedules worker` CLI and the daemon lifecycle (when
+ * `schedules.worker.enabled` is set) need to probe, spawn, and stop this
+ * process. The generic PID-file mechanics live in `util/worker-process.ts`;
+ * this module binds them to the schedule worker's PID path and entry point.
+ */
+
+import { getConfig } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+import { getScheduleWorkerPidPath } from "../util/platform.js";
+import {
+  probeWorkerPidFile,
+  spawnWorkerProcess,
+  type SpawnWorkerProcessOptions,
+  stopWorkerProcess,
+  WorkerProcessSpawnError,
+  type WorkerProcessStatus,
+} from "../util/worker-process.js";
+
+const log = getLogger("schedule-worker-control");
+
+/**
+ * Inspect the PID file to determine whether the schedule worker process is
+ * alive. A stale PID file (pointing at a dead process) is cleaned up and
+ * reported as not_running.
+ */
+export function probeScheduleWorker(): WorkerProcessStatus {
+  return probeWorkerPidFile(getScheduleWorkerPidPath());
+}
+
+export class ScheduleWorkerSpawnError extends WorkerProcessSpawnError {}
+
+/**
+ * Spawn the schedule worker as a background process. If a worker is already
+ * running, returns its PID with `alreadyRunning: true` rather than spawning a
+ * second one. Throws {@link ScheduleWorkerSpawnError} if the child crashes
+ * during startup or never writes its PID file within the wait window.
+ *
+ * Beyond the generic option semantics documented on
+ * {@link SpawnWorkerProcessOptions}: callers whose failure path leaves
+ * `schedules.worker.enabled` off (the start route) should set
+ * `terminateOnTimeout` so a worker reported as failed cannot come up later
+ * and run schedules alongside the daemon's scheduler; the daemon's boot
+ * spawn leaves the flag on, so a late worker there is the desired sole
+ * schedule runner and passes `false`.
+ */
+export async function spawnScheduleWorkerProcess(
+  opts: SpawnWorkerProcessOptions = {},
+): Promise<{ pid: number; alreadyRunning: boolean }> {
+  try {
+    return await spawnWorkerProcess({
+      pidPath: getScheduleWorkerPidPath(),
+      entry: new URL("./worker.ts", import.meta.url),
+      workerLabel: "Schedule worker",
+      options: opts,
+    });
+  } catch (err) {
+    if (err instanceof WorkerProcessSpawnError) {
+      throw new ScheduleWorkerSpawnError(err.message);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Send SIGTERM to the schedule worker process if it is actually running.
+ * Returns the status observed before signalling. Only throws if
+ * `process.kill` itself fails (e.g. EPERM) — a not-running worker is a no-op.
+ */
+export function stopScheduleWorkerProcess(): WorkerProcessStatus {
+  return stopWorkerProcess(getScheduleWorkerPidPath());
+}
+
+/**
+ * Daemon-lifecycle entry point: spawn the schedule worker as a child of the
+ * daemon (`detached: false`, so it appears in `assistant ps` and is torn down
+ * on shutdown) when `schedules.worker.enabled` is set. Fire-and-forget — a
+ * worker failure must never block boot. The flag stays on either way, so a
+ * worker that comes up late is the desired sole schedule runner
+ * (`terminateOnTimeout` is deliberately not set).
+ */
+export function startScheduleWorkerIfEnabled(): void {
+  if (getConfig().schedules?.worker?.enabled !== true) {
+    return;
+  }
+  void spawnScheduleWorkerProcess({ detached: false })
+    .then((r) =>
+      log.info(
+        { pid: r.pid, alreadyRunning: r.alreadyRunning },
+        r.alreadyRunning
+          ? "Schedule worker process already running — reusing it"
+          : "Schedule worker process started at boot",
+      ),
+    )
+    .catch((err) =>
+      log.warn({ err }, "Failed to start schedule worker at boot"),
+    );
+}
+
+/**
+ * Daemon-lifecycle entry point: SIGTERM the schedule worker process if it is
+ * running. Keyed off live state rather than config: it may have been spawned
+ * at startup or out of band via `assistant schedules worker start`. Never
+ * throws.
+ */
+export function stopScheduleWorker(): void {
+  try {
+    const status = stopScheduleWorkerProcess();
+    if (status.status === "running") {
+      log.info({ pid: status.pid }, "Sent SIGTERM to schedule worker process");
+    }
+  } catch (err) {
+    log.warn({ err }, "Failed to stop schedule worker process (non-fatal)");
+  }
+}