@vellumai/assistant 0.6.5 → 0.6.6

package/src/runtime/routes/schedule-routes.ts

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import { bootstrapConversation } from "../../memory/conversation-bootstrap.js";
 import { getConversation } from "../../memory/conversation-crud.js";
+import { runScript } from "../../schedule/run-script.js";
 import {
   cancelSchedule,
   completeScheduleRun,
@@ -16,6 +17,7 @@ import {
   describeCronExpression,
   getLastScheduleConversationId,
   getSchedule,
+  getScheduleRuns,
   listSchedules,
   updateSchedule,
 } from "../../schedule/schedule-store.js";
@@ -46,6 +48,7 @@ function handleListSchedules(): Response {
       cronExpression: j.cronExpression,
       timezone: j.timezone,
       message: j.message,
+      script: j.script,
       nextRunAt: j.nextRunAt,
       lastRunAt: j.lastRunAt,
       lastStatus: j.lastStatus,
@@ -108,7 +111,7 @@ function handleCancelSchedule(id: string): Response {
   return handleListSchedules();
 }
 
-const VALID_MODES = ["notify", "execute"] as const;
+const VALID_MODES = ["notify", "execute", "script"] as const;
 const VALID_ROUTING_INTENTS = [
   "single_channel",
   "multi_channel",
@@ -149,6 +152,7 @@ function handleUpdateSchedule(
     "expression",
     "timezone",
     "message",
+    "script",
     "mode",
     "routingIntent",
     "quiet",
@@ -178,6 +182,28 @@ function handleUpdateSchedule(
   return handleListSchedules();
 }
 
+function handleListScheduleRuns(id: string, limit: number): Response {
+  const schedule = getSchedule(id);
+  if (!schedule) {
+    return httpError("NOT_FOUND", "Schedule not found", 404);
+  }
+  const runs = getScheduleRuns(id, limit);
+  return Response.json({
+    runs: runs.map((r) => ({
+      id: r.id,
+      jobId: r.jobId,
+      status: r.status,
+      startedAt: r.startedAt,
+      finishedAt: r.finishedAt,
+      durationMs: r.durationMs,
+      output: r.output,
+      error: r.error,
+      conversationId: r.conversationId,
+      createdAt: r.createdAt,
+    })),
+  });
+}
+
 async function handleRunScheduleNow(
   id: string,
   sendMessageDeps?: SendMessageDeps,
@@ -187,6 +213,38 @@ async function handleRunScheduleNow(
     return httpError("NOT_FOUND", "Schedule not found", 404);
   }
 
+  // ── Script mode (shell command, no LLM) ──────────────────────────
+  if (schedule.mode === "script") {
+    if (!schedule.script) {
+      return httpError(
+        "BAD_REQUEST",
+        "Script schedule has no script command",
+        400,
+      );
+    }
+    const runId = createScheduleRun(schedule.id, `script:${schedule.id}`);
+    try {
+      log.info(
+        { jobId: schedule.id, name: schedule.name },
+        "Executing script schedule manually via HTTP (run now)",
+      );
+      const result = await runScript(schedule.script);
+      completeScheduleRun(runId, {
+        status: result.exitCode === 0 ? "ok" : "error",
+        output: result.stdout || undefined,
+        error: result.stderr || undefined,
+      });
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      log.warn(
+        { err, jobId: schedule.id, name: schedule.name },
+        "Manual script schedule execution failed",
+      );
+      completeScheduleRun(runId, { status: "error", error: errorMsg });
+    }
+    return handleListSchedules();
+  }
+
   // Check if message is a task invocation (run_task:<task_id>)
   const taskMatch = schedule.message.match(/^run_task:(\S+)$/);
   if (taskMatch) {
@@ -205,10 +263,12 @@ async function handleRunScheduleNow(
               "sendMessageDeps not available for schedule execution",
             );
           }
-          const conversation =
-            await sendMessageDeps.getOrCreateConversation(conversationId, {
+          const conversation = await sendMessageDeps.getOrCreateConversation(
+            conversationId,
+            {
               trustContext: SCHEDULE_GUARDIAN_TRUST_CONTEXT,
-            });
+            },
+          );
           conversation.taskRunId = taskRunId;
           try {
             await conversation.processMessage(
@@ -285,10 +345,12 @@ async function handleRunScheduleNow(
     if (!sendMessageDeps) {
       throw new Error("sendMessageDeps not available for schedule execution");
     }
-    const activeConversation =
-      await sendMessageDeps.getOrCreateConversation(conversationId, {
+    const activeConversation = await sendMessageDeps.getOrCreateConversation(
+      conversationId,
+      {
         trustContext: SCHEDULE_GUARDIAN_TRUST_CONTEXT,
-      });
+      },
+    );
     activeConversation.taskRunId = undefined;
     await activeConversation.processMessage(
       schedule.message,
@@ -331,6 +393,24 @@ export function scheduleRouteDefinitions(deps: {
       }),
       handler: () => handleListSchedules(),
     },
+    {
+      endpoint: "schedules/:id/runs",
+      method: "GET",
+      policyKey: "schedules",
+      summary: "List schedule runs",
+      description: "Return recent invocation history for a schedule.",
+      tags: ["schedules"],
+      responseBody: z.object({
+        runs: z.array(z.unknown()).describe("Schedule run objects"),
+      }),
+      handler: ({ params, url }) => {
+        const rawLimit = Number(url.searchParams.get("limit") ?? 10);
+        const limit = Number.isFinite(rawLimit)
+          ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
+          : 10;
+        return handleListScheduleRuns(params.id, limit);
+      },
+    },
     {
       endpoint: "schedules/:id/toggle",
       method: "POST",
@@ -376,7 +456,8 @@ export function scheduleRouteDefinitions(deps: {
         expression: z.string(),
         timezone: z.string(),
         message: z.string(),
-        mode: z.string().describe("notify or execute"),
+        script: z.string().nullable().describe("Shell command for script mode"),
+        mode: z.string().describe("notify, execute, or script"),
         routingIntent: z
           .string()
           .describe("single_channel, multi_channel, or all_channels"),

package/src/runtime/skill-route-registry.ts

@@ -1,9 +1,16 @@
 /**
  * Registry for skill-provided HTTP route handlers.
  *
- * Skills register route matchers + handlers at initialization time. The
- * runtime HTTP server checks the registry for each inbound request before
- * falling through to its own route table.
+ * Skills and plugins register route matchers + handlers at initialization
+ * time. The runtime HTTP server checks the registry for each inbound request
+ * before falling through to its own route table.
+ *
+ * Registrations are identified by an opaque {@link SkillRouteHandle} returned
+ * from {@link registerSkillRoute}. Callers must pass that exact handle back
+ * to {@link unregisterSkillRoute} to remove the registration — pattern text
+ * is intentionally not a stable key, because two owners can legitimately
+ * register the same regex, and keying on `source + flags` would let one
+ * owner's teardown silently drop another owner's route.
  */
 
 import { getLogger } from "../util/logger.js";
@@ -23,17 +30,62 @@ export type SkillRouteMatch =
   | { kind: "match"; route: SkillRoute; match: RegExpMatchArray }
   | { kind: "methodMismatch"; allow: string[] };
 
-const routes: SkillRoute[] = [];
+/**
+ * Opaque token returned from {@link registerSkillRoute}. The token has no
+ * observable fields — callers must treat it as a black box whose only valid
+ * use is to pass it to {@link unregisterSkillRoute}. Identity comparison on
+ * the token is what the registry keys against, so every call to
+ * `registerSkillRoute` returns a fresh handle even when the route's
+ * `pattern`/`methods`/`handler` are deep-equal to an existing entry.
+ */
+declare const skillRouteHandleBrand: unique symbol;
+export interface SkillRouteHandle {
+  readonly [skillRouteHandleBrand]: true;
+}
+
+interface RegisteredRoute {
+  readonly handle: SkillRouteHandle;
+  readonly route: SkillRoute;
+}
+
+const routes: RegisteredRoute[] = [];
 
 /**
- * Register a skill-provided HTTP route. Called by skills at initialization time.
+ * Register a skill- or plugin-provided HTTP route. Called at initialization
+ * time. Returns an opaque handle the caller must retain and pass back to
+ * {@link unregisterSkillRoute} at teardown time. Do not attempt to derive
+ * the handle from the route's pattern — identity is the only stable key.
  */
-export function registerSkillRoute(route: SkillRoute): void {
-  routes.push(route);
+export function registerSkillRoute(route: SkillRoute): SkillRouteHandle {
+  const handle = Object.freeze({}) as SkillRouteHandle;
+  routes.push({ handle, route });
   log.info(
     { pattern: route.pattern.source, methods: route.methods },
     "Skill route registered",
   );
+  return handle;
+}
+
+/**
+ * Unregister a previously-registered skill route by handle.
+ *
+ * Returns `true` if a route was removed, `false` otherwise. Not finding a
+ * match is not an error: the plugin-shutdown path calls this best-effort for
+ * every handle a plugin retained, and a stale handle (e.g. the registry was
+ * cleared externally) should not crash shutdown.
+ */
+export function unregisterSkillRoute(handle: SkillRouteHandle): boolean {
+  const index = routes.findIndex((entry) => entry.handle === handle);
+  if (index === -1) {
+    log.warn({}, "unregisterSkillRoute: no matching route found for handle");
+    return false;
+  }
+  const [removed] = routes.splice(index, 1);
+  log.info(
+    { pattern: removed!.route.pattern.source },
+    "Skill route unregistered",
+  );
+  return true;
 }
 
 /**
@@ -55,17 +107,25 @@ export function matchSkillRoute(
   method: string,
 ): SkillRouteMatch | null {
   const pathMatches: SkillRoute[] = [];
-  for (const route of routes) {
-    const match = path.match(route.pattern);
+  for (const entry of routes) {
+    const match = path.match(entry.route.pattern);
     if (!match) continue;
-    if (route.methods.includes(method)) {
-      return { kind: "match", route, match };
+    if (entry.route.methods.includes(method)) {
+      return { kind: "match", route: entry.route, match };
     }
-    pathMatches.push(route);
+    pathMatches.push(entry.route);
   }
   if (pathMatches.length === 0) return null;
-  const allow = Array.from(
-    new Set(pathMatches.flatMap((r) => r.methods)),
-  );
+  const allow = Array.from(new Set(pathMatches.flatMap((r) => r.methods)));
   return { kind: "methodMismatch", allow };
 }
+
+/**
+ * Test-only helper — drops every registered route. Production code has no
+ * legitimate need for this; a real shutdown walks the handles each owner
+ * retained. Exported so tests that bypass the normal shutdown path (e.g.
+ * those that crash mid-bootstrap) can reset registry state between cases.
+ */
+export function resetSkillRoutesForTests(): void {
+  routes.length = 0;
+}

package/src/schedule/run-script.ts

@@ -0,0 +1,68 @@
+import { buildSanitizedEnv } from "../tools/terminal/safe-env.js";
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+
+const log = getLogger("run-script");
+
+/** Maximum combined stdout + stderr captured (bytes). */
+const MAX_OUTPUT_BYTES = 10_000;
+/** Default timeout for script execution (ms). */
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export interface ScriptResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Run a shell command and capture its output.
+ *
+ * Uses Bun.spawn with /bin/sh so the command string supports pipes,
+ * redirects, and shell builtins. Output is truncated to
+ * {@link MAX_OUTPUT_BYTES} to keep schedule_runs rows bounded.
+ */
+export async function runScript(
+  command: string,
+  options?: { timeoutMs?: number; cwd?: string },
+): Promise<ScriptResult> {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const cwd = options?.cwd ?? getWorkspaceDir();
+
+  log.info({ command, cwd, timeoutMs }, "Running script");
+
+  const proc = Bun.spawn(["sh", "-c", command], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: buildSanitizedEnv(),
+  });
+
+  // Race process completion against a timeout
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    const timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      reject(new Error(`Script timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref();
+    // Clean up timer if process finishes first
+    proc.exited.then(() => clearTimeout(timer));
+  });
+
+  const exitCode = await Promise.race([proc.exited, timeoutPromise]);
+
+  const stdout = truncate(await new Response(proc.stdout).text());
+  const stderr = truncate(await new Response(proc.stderr).text());
+
+  log.info(
+    { command, exitCode, stdoutLen: stdout.length, stderrLen: stderr.length },
+    "Script completed",
+  );
+
+  return { exitCode, stdout, stderr };
+}
+
+function truncate(text: string): string {
+  if (text.length <= MAX_OUTPUT_BYTES) return text;
+  return text.slice(0, MAX_OUTPUT_BYTES) + "\n... (truncated)";
+}

package/src/schedule/schedule-store.ts

@@ -14,7 +14,7 @@ import type { ScheduleSyntax } from "./recurrence-types.js";
 
 const logger = getLogger("schedule-store");
 
-export type ScheduleMode = "notify" | "execute";
+export type ScheduleMode = "notify" | "execute" | "script";
 export type RoutingIntent = "single_channel" | "multi_channel" | "all_channels";
 export type ScheduleStatus = "active" | "firing" | "fired" | "cancelled";
 
@@ -27,6 +27,7 @@ export interface ScheduleJob {
   cronExpression: string | null;
   timezone: string | null;
   message: string;
+  script: string | null;
   nextRunAt: number;
   lastRunAt: number | null;
   lastStatus: string | null;
@@ -85,6 +86,7 @@ export function createSchedule(params: {
   cronExpression?: string | null;
   timezone?: string | null;
   message: string;
+  script?: string | null;
   enabled?: boolean;
   createdBy?: string;
   syntax?: ScheduleSyntax;
@@ -142,6 +144,7 @@ export function createSchedule(params: {
     scheduleSyntax: syntax,
     timezone,
     message: params.message,
+    script: params.script ?? null,
     nextRunAt,
     lastRunAt: null as number | null,
     lastStatus: null as string | null,
@@ -217,6 +220,7 @@ export function updateSchedule(
     cronExpression?: string;
     timezone?: string | null;
     message?: string;
+    script?: string | null;
     enabled?: boolean;
     syntax?: ScheduleSyntax;
     expression?: string;
@@ -273,6 +277,7 @@ export function updateSchedule(
   if (updates.syntax !== undefined) set.scheduleSyntax = newSyntax;
   if (updates.timezone !== undefined) set.timezone = updates.timezone;
   if (updates.message !== undefined) set.message = updates.message;
+  if (updates.script !== undefined) set.script = updates.script;
   if (updates.enabled !== undefined) set.enabled = updates.enabled;
   if (updates.mode !== undefined) set.mode = updates.mode;
   if (updates.routingIntent !== undefined)
@@ -777,6 +782,7 @@ function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
     cronExpression: row.cronExpression,
     timezone: row.timezone,
     message: row.message,
+    script: row.script ?? null,
     nextRunAt: row.nextRunAt,
     lastRunAt: row.lastRunAt,
     lastStatus: row.lastStatus,

package/src/schedule/scheduler.ts

@@ -11,6 +11,7 @@ import {
   type WatcherNotifier,
 } from "../watcher/engine.js";
 import { hasSetConstructs } from "./recurrence-engine.js";
+import { runScript, type ScriptResult } from "./run-script.js";
 import {
   claimDueSchedules,
   completeOneShot,
@@ -49,8 +50,6 @@ export type ScheduleNotifyModeNotifier = (payload: {
   routingHints: Record<string, unknown>;
 }) => void | Promise<void>;
 
-export type ScheduleNotifier = (schedule: { id: string; name: string }) => void;
-
 export type ScheduleConversationCreatedNotifier = (info: {
   conversationId: string;
   scheduleJobId: string;
@@ -67,7 +66,6 @@ const TICK_INTERVAL_MS = 15_000;
 export function startScheduler(
   processMessage: ScheduleMessageProcessor,
   notifyScheduleOneShot: ScheduleNotifyModeNotifier,
-  notifySchedule: ScheduleNotifier,
   watcherNotifier?: WatcherNotifier,
   watcherEscalator?: WatcherEscalator,
   onScheduleConversationCreated?: ScheduleConversationCreatedNotifier,
@@ -82,7 +80,6 @@ export function startScheduler(
       await runScheduleOnce(
         processMessage,
         notifyScheduleOneShot,
-        notifySchedule,
         watcherNotifier,
         watcherEscalator,
         onScheduleConversationCreated,
@@ -105,7 +102,6 @@ export function startScheduler(
       return runScheduleOnce(
         processMessage,
         notifyScheduleOneShot,
-        notifySchedule,
         watcherNotifier,
         watcherEscalator,
         onScheduleConversationCreated,
@@ -121,7 +117,6 @@ export function startScheduler(
 async function runScheduleOnce(
   processMessage: ScheduleMessageProcessor,
   notifyScheduleOneShot: ScheduleNotifyModeNotifier,
-  notifySchedule: ScheduleNotifier,
   watcherNotifier?: WatcherNotifier,
   watcherEscalator?: WatcherEscalator,
   onScheduleConversationCreated?: ScheduleConversationCreatedNotifier,
@@ -185,6 +180,53 @@ async function runScheduleOnce(
       continue;
     }
 
+    // ── Script mode (shell command, no LLM) ────────────────────────
+    if (job.mode === "script") {
+      if (!job.script) {
+        log.warn(
+          { jobId: job.id, name: job.name },
+          "Script schedule has no script command — skipping",
+        );
+        processed += 1;
+        continue;
+      }
+      const runId = createScheduleRun(job.id, `script:${job.id}`);
+      try {
+        log.info(
+          { jobId: job.id, name: job.name, isOneShot },
+          "Executing script schedule",
+        );
+        const result: ScriptResult = await runScript(job.script);
+        completeScheduleRun(runId, {
+          status: result.exitCode === 0 ? "ok" : "error",
+          output: result.stdout || undefined,
+          error: result.stderr || undefined,
+        });
+        if (result.exitCode === 0) {
+          if (!job.quiet) {
+            emitScheduleFeedEvent({
+              title: job.name,
+              summary: "Script ran.",
+              dedupKey: `schedule-run:${runId}`,
+            });
+          }
+          if (isOneShot) completeOneShot(job.id);
+        } else {
+          if (isOneShot) failOneShot(job.id);
+        }
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        log.warn(
+          { err, jobId: job.id, name: job.name, isOneShot },
+          "Script schedule execution failed",
+        );
+        completeScheduleRun(runId, { status: "error", error: errorMsg });
+        if (isOneShot) failOneShot(job.id);
+      }
+      processed += 1;
+      continue;
+    }
+
     // ── Execute mode ────────────────────────────────────────────────
 
     // Check if message is a task invocation (run_task:<task_id>)
@@ -241,7 +283,6 @@ async function runScheduleOnce(
         } else {
           completeScheduleRun(runId, { status: "ok" });
           if (!job.quiet) {
-            notifySchedule({ id: job.id, name: job.name });
             emitScheduleFeedEvent({
               title: job.name,
               summary: "Scheduled task ran.",
@@ -340,7 +381,6 @@ async function runScheduleOnce(
       });
       completeScheduleRun(runId, { status: "ok" });
       if (!job.quiet) {
-        notifySchedule({ id: job.id, name: job.name });
         emitScheduleFeedEvent({
           title: job.name,
           summary: isOneShot ? "One-shot reminder ran." : "Scheduled job ran.",

package/src/skills/catalog-cache.ts

@@ -37,6 +37,16 @@ export async function getCatalog(): Promise<CatalogSkill[]> {
       catalog = remote;
     }
   } catch (err) {
+    if (cachedCatalog) {
+      log.warn(
+        { err },
+        "Failed to fetch Vellum catalog, keeping stale merged cache",
+      );
+      // Reset the TTL window so subsequent calls during the outage are served
+      // from cache instead of re-entering fetchCatalog() on every call.
+      cacheTimestamp = Date.now();
+      return cachedCatalog;
+    }
     if (local.length > 0) {
       log.warn(
         { err },
@@ -44,11 +54,8 @@ export async function getCatalog(): Promise<CatalogSkill[]> {
       );
       catalog = local;
     } else {
-      log.warn(
-        { err },
-        "Failed to fetch Vellum catalog, using stale cache or empty",
-      );
-      return cachedCatalog ?? [];
+      log.warn({ err }, "Failed to fetch Vellum catalog, returning empty");
+      return [];
     }
   }
   cachedCatalog = catalog;