@hasna/prompts 0.3.4 → 0.3.5

package/dist/cli/index.js

@@ -2229,6 +2229,25 @@ function runMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_usage_log_used_at ON usage_log(used_at);
       `
     },
+    {
+      name: "008_schedules",
+      sql: `
+        CREATE TABLE IF NOT EXISTS prompt_schedules (
+          id TEXT PRIMARY KEY,
+          prompt_id TEXT NOT NULL REFERENCES prompts(id) ON DELETE CASCADE,
+          prompt_slug TEXT NOT NULL,
+          cron TEXT NOT NULL,
+          vars TEXT NOT NULL DEFAULT '{}',
+          agent_id TEXT,
+          last_run_at TEXT,
+          next_run_at TEXT NOT NULL,
+          run_count INTEGER NOT NULL DEFAULT 0,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_prompt_schedules_next_run ON prompt_schedules(next_run_at);
+        CREATE INDEX IF NOT EXISTS idx_prompt_schedules_prompt_id ON prompt_schedules(prompt_id);
+      `
+    },
     {
       name: "002_fts5",
       sql: `
@@ -3167,6 +3186,152 @@ function lintAll(prompts) {
   return prompts.map((p) => ({ prompt: p, issues: lintPrompt(p) })).filter((r) => r.issues.length > 0);
 }
 
+// src/db/schedules.ts
+init_database();
+
+// src/lib/cron.ts
+function parseField(field, min, max) {
+  if (field === "*") {
+    return range(min, max);
+  }
+  const result = [];
+  for (const part of field.split(",")) {
+    if (part.includes("/")) {
+      const [rangeOrStar, stepStr] = part.split("/");
+      const step = parseInt(stepStr ?? "1", 10);
+      const start = rangeOrStar === "*" ? min : parseInt(rangeOrStar ?? String(min), 10);
+      for (let v = start;v <= max; v += step)
+        result.push(v);
+    } else if (part.includes("-")) {
+      const [fromStr, toStr] = part.split("-");
+      const from = parseInt(fromStr ?? String(min), 10);
+      const to = parseInt(toStr ?? String(max), 10);
+      for (let v = from;v <= to; v++)
+        result.push(v);
+    } else {
+      result.push(parseInt(part, 10));
+    }
+  }
+  return [...new Set(result)].sort((a, b) => a - b).filter((v) => v >= min && v <= max);
+}
+function range(min, max) {
+  const r = [];
+  for (let i = min;i <= max; i++)
+    r.push(i);
+  return r;
+}
+function getNextRunTime(cronExpr, from = new Date) {
+  const parts = cronExpr.trim().split(/\s+/);
+  if (parts.length !== 5)
+    throw new Error(`Invalid cron expression (need 5 fields): ${cronExpr}`);
+  const [minField, hourField, domField, monField, dowField] = parts;
+  const minutes = parseField(minField, 0, 59);
+  const hours = parseField(hourField, 0, 23);
+  const doms = parseField(domField, 1, 31);
+  const months = parseField(monField, 1, 12);
+  const dows = parseField(dowField, 0, 6);
+  const next = new Date(from);
+  next.setSeconds(0, 0);
+  next.setMinutes(next.getMinutes() + 1);
+  const limit = new Date(from);
+  limit.setFullYear(limit.getFullYear() + 4);
+  while (next <= limit) {
+    const mon = next.getMonth() + 1;
+    if (!months.includes(mon)) {
+      next.setDate(1);
+      next.setHours(0, 0, 0, 0);
+      next.setMonth(next.getMonth() + 1);
+      continue;
+    }
+    const dom = next.getDate();
+    const dow = next.getDay();
+    const domMatch = domField === "*" || doms.includes(dom);
+    const dowMatch = dowField === "*" || dows.includes(dow);
+    const dayMatch = domField === "*" && dowField === "*" ? true : domField !== "*" && dowField !== "*" ? domMatch || dowMatch : domField !== "*" ? domMatch : dowMatch;
+    if (!dayMatch) {
+      next.setDate(next.getDate() + 1);
+      next.setHours(0, 0, 0, 0);
+      continue;
+    }
+    const h = next.getHours();
+    const validHour = hours.find((v) => v >= h);
+    if (validHour === undefined) {
+      next.setDate(next.getDate() + 1);
+      next.setHours(0, 0, 0, 0);
+      continue;
+    }
+    if (validHour > h) {
+      next.setHours(validHour, 0, 0, 0);
+    }
+    const m = next.getMinutes();
+    const validMin = minutes.find((v) => v >= m);
+    if (validMin === undefined) {
+      next.setHours(next.getHours() + 1, 0, 0, 0);
+      continue;
+    }
+    next.setMinutes(validMin);
+    return next;
+  }
+  throw new Error(`Could not find next run time for cron: ${cronExpr}`);
+}
+function validateCron(expr) {
+  try {
+    getNextRunTime(expr, new Date);
+    return null;
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+}
+
+// src/db/schedules.ts
+function rowToSchedule(row) {
+  return {
+    ...row,
+    vars: JSON.parse(row.vars)
+  };
+}
+function createSchedule(input) {
+  const db = getDatabase();
+  const id = `SCH-${Math.random().toString(36).slice(2, 8).toUpperCase()}`;
+  const next_run_at = getNextRunTime(input.cron).toISOString();
+  const vars = JSON.stringify(input.vars ?? {});
+  db.run(`INSERT INTO prompt_schedules (id, prompt_id, prompt_slug, cron, vars, agent_id, next_run_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [id, input.prompt_id, input.prompt_slug, input.cron, vars, input.agent_id ?? null, next_run_at]);
+  const row = db.query("SELECT * FROM prompt_schedules WHERE id = ?").get(id);
+  return rowToSchedule(row);
+}
+function listSchedules(promptId) {
+  const db = getDatabase();
+  const rows = promptId ? db.query("SELECT * FROM prompt_schedules WHERE prompt_id = ? ORDER BY next_run_at").all(promptId) : db.query("SELECT * FROM prompt_schedules ORDER BY next_run_at").all();
+  return rows.map(rowToSchedule);
+}
+function deleteSchedule(id) {
+  const db = getDatabase();
+  db.run("DELETE FROM prompt_schedules WHERE id = ?", [id]);
+}
+function getDueSchedules() {
+  const db = getDatabase();
+  const now = new Date().toISOString();
+  const rows = db.query(`SELECT ps.*, p.body as prompt_body
+       FROM prompt_schedules ps
+       JOIN prompts p ON p.id = ps.prompt_id
+       WHERE ps.next_run_at <= ?
+       ORDER BY ps.next_run_at`).all(now);
+  const due = [];
+  for (const row of rows) {
+    const schedule = rowToSchedule(row);
+    let rendered = row.prompt_body;
+    for (const [k, v] of Object.entries(schedule.vars)) {
+      rendered = rendered.replace(new RegExp(`\\{\\{\\s*${k}[^}]*\\}\\}`, "g"), v);
+    }
+    rendered = rendered.replace(/\{\{([^|}]+)\|([^}]*)\}\}/g, (_, _name, def) => def);
+    const newNext = getNextRunTime(schedule.cron).toISOString();
+    db.run(`UPDATE prompt_schedules SET last_run_at = ?, next_run_at = ?, run_count = run_count + 1 WHERE id = ?`, [now, newNext, schedule.id]);
+    due.push({ ...schedule, rendered, prompt_body: row.prompt_body });
+  }
+  return due;
+}
+
 // src/lib/audit.ts
 init_database();
 function runAudit() {
@@ -4332,4 +4497,131 @@ ${chalk.green(`Created: ${imported.created}`)}  ${chalk.yellow(`Updated: ${impor
     handleError(e);
   }
 });
+program2.command("remove <id>").alias("rm").alias("uninstall").description("Remove a prompt (alias for delete)").option("-y, --yes", "Skip confirmation").action(async (id, opts) => {
+  try {
+    const prompt = getPrompt(id);
+    if (!prompt)
+      handleError(`Prompt not found: ${id}`);
+    if (!opts.yes && !isJson()) {
+      const { createInterface } = await import("readline");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      await new Promise((resolve) => {
+        rl.question(chalk.yellow(`Remove "${prompt.slug}"? [y/N] `), (ans) => {
+          rl.close();
+          if (ans.toLowerCase() !== "y") {
+            console.log("Cancelled.");
+            process.exit(0);
+          }
+          resolve();
+        });
+      });
+    }
+    deletePrompt(id);
+    if (isJson())
+      output({ deleted: true, id: prompt.id });
+    else
+      console.log(chalk.red(`Removed ${prompt.slug}`));
+  } catch (e) {
+    handleError(e);
+  }
+});
+var scheduleCmd = program2.command("schedule").description("Manage prompt schedules");
+scheduleCmd.command("add <id> <cron>").description("Schedule a prompt to run on a cron (5-field: min hour dom mon dow)").option("--vars <json>", `JSON object of template variables, e.g. '{"name":"Alice"}'`).option("--agent <id>", "Agent ID to associate").action((id, cron, opts) => {
+  try {
+    const cronError = validateCron(cron);
+    if (cronError)
+      handleError(`Invalid cron: ${cronError}`);
+    const prompt = getPrompt(id);
+    if (!prompt)
+      handleError(`Prompt not found: ${id}`);
+    const vars = opts.vars ? JSON.parse(opts.vars) : undefined;
+    const schedule = createSchedule({ prompt_id: prompt.id, prompt_slug: prompt.slug, cron, vars, agent_id: opts.agent });
+    if (isJson()) {
+      output(schedule);
+      return;
+    }
+    console.log(chalk.green(`Scheduled "${prompt.slug}" [${schedule.id}]`));
+    console.log(`  Cron:     ${cron}`);
+    console.log(`  Next run: ${schedule.next_run_at}`);
+  } catch (e) {
+    handleError(e);
+  }
+});
+scheduleCmd.command("list [id]").description("List schedules, optionally filtered by prompt ID").action((id) => {
+  try {
+    const schedules = listSchedules(id);
+    if (isJson()) {
+      output(schedules);
+      return;
+    }
+    if (!schedules.length) {
+      console.log(chalk.gray("No schedules."));
+      return;
+    }
+    for (const s of schedules) {
+      console.log(`${chalk.bold(s.id)}  ${chalk.cyan(s.prompt_slug)}  cron:${s.cron}  next:${s.next_run_at}  runs:${s.run_count}`);
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
+scheduleCmd.command("remove <scheduleId>").alias("delete").description("Remove a prompt schedule").action((scheduleId) => {
+  try {
+    deleteSchedule(scheduleId);
+    if (isJson())
+      output({ deleted: true, id: scheduleId });
+    else
+      console.log(chalk.red(`Removed schedule ${scheduleId}`));
+  } catch (e) {
+    handleError(e);
+  }
+});
+scheduleCmd.command("due").description("Show and execute all due schedules").option("--dry-run", "Show due prompts without marking them as ran").action((opts) => {
+  try {
+    const due = getDueSchedules();
+    if (!due.length) {
+      console.log(chalk.gray("No prompts due."));
+      return;
+    }
+    if (isJson()) {
+      output(due);
+      return;
+    }
+    for (const d of due) {
+      console.log(chalk.bold(`
+[${d.id}] ${d.prompt_slug}`));
+      console.log(chalk.gray(`Next run: ${d.next_run_at}  |  Runs: ${d.run_count}`));
+      console.log(chalk.white(d.rendered));
+    }
+    if (!opts.dryRun)
+      console.log(chalk.green(`
+\u2713 Marked ${due.length} schedule(s) as ran.`));
+  } catch (e) {
+    handleError(e);
+  }
+});
+scheduleCmd.command("next <cron>").description("Preview when a cron expression will fire").option("-n, --count <n>", "Number of runs to show", "5").action((cron, opts) => {
+  try {
+    const cronError = validateCron(cron);
+    if (cronError)
+      handleError(`Invalid cron: ${cronError}`);
+    const count = parseInt(opts.count ?? "5", 10);
+    const runs = [];
+    let from = new Date;
+    for (let i = 0;i < count; i++) {
+      const next = getNextRunTime(cron, from);
+      runs.push(next.toISOString());
+      from = next;
+    }
+    if (isJson()) {
+      output({ cron, next_runs: runs });
+      return;
+    }
+    console.log(chalk.bold(`Next ${count} runs for "${cron}":`));
+    for (const r of runs)
+      console.log(`  ${r}`);
+  } catch (e) {
+    handleError(e);
+  }
+});
 program2.parse();

package/dist/db/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAMrC,wBAAgB,SAAS,IAAI,MAAM,CAsBlC;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAmBtC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AAGD,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAyJD,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0B5E;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAM5C;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkC3E"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAMrC,wBAAgB,SAAS,IAAI,MAAM,CAsBlC;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAmBtC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AAGD,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AA4KD,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0B5E;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAM5C;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkC3E"}

package/dist/db/schedules.d.ts

@@ -0,0 +1,29 @@
+export interface PromptSchedule {
+    id: string;
+    prompt_id: string;
+    prompt_slug: string;
+    cron: string;
+    vars: Record<string, string>;
+    agent_id: string | null;
+    last_run_at: string | null;
+    next_run_at: string;
+    run_count: number;
+    created_at: string;
+}
+export declare function createSchedule(input: {
+    prompt_id: string;
+    prompt_slug: string;
+    cron: string;
+    vars?: Record<string, string>;
+    agent_id?: string;
+}): PromptSchedule;
+export declare function listSchedules(promptId?: string): PromptSchedule[];
+export declare function getSchedule(id: string): PromptSchedule | null;
+export declare function deleteSchedule(id: string): void;
+export interface DueSchedule extends PromptSchedule {
+    rendered: string;
+    prompt_body: string;
+}
+export declare function getDueSchedules(): DueSchedule[];
+export declare function markScheduleRan(id: string): PromptSchedule | null;
+//# sourceMappingURL=schedules.d.ts.map

package/dist/db/schedules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedules.d.ts","sourceRoot":"","sources":["../../src/db/schedules.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAsBD,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,cAAc,CAgBjB;AAED,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAMjE;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAI7D;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG/C;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,eAAe,IAAI,WAAW,EAAE,CAoC/C;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAWjE"}

package/dist/index.js

@@ -148,6 +148,25 @@ function runMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_usage_log_used_at ON usage_log(used_at);
       `
     },
+    {
+      name: "008_schedules",
+      sql: `
+        CREATE TABLE IF NOT EXISTS prompt_schedules (
+          id TEXT PRIMARY KEY,
+          prompt_id TEXT NOT NULL REFERENCES prompts(id) ON DELETE CASCADE,
+          prompt_slug TEXT NOT NULL,
+          cron TEXT NOT NULL,
+          vars TEXT NOT NULL DEFAULT '{}',
+          agent_id TEXT,
+          last_run_at TEXT,
+          next_run_at TEXT NOT NULL,
+          run_count INTEGER NOT NULL DEFAULT 0,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_prompt_schedules_next_run ON prompt_schedules(next_run_at);
+        CREATE INDEX IF NOT EXISTS idx_prompt_schedules_prompt_id ON prompt_schedules(prompt_id);
+      `
+    },
     {
       name: "002_fts5",
       sql: `

package/dist/lib/cron.d.ts

@@ -0,0 +1,3 @@
+export declare function getNextRunTime(cronExpr: string, from?: Date): Date;
+export declare function validateCron(expr: string): string | null;
+//# sourceMappingURL=cron.d.ts.map

package/dist/lib/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../../src/lib/cron.ts"],"names":[],"mappings":"AAiCA,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,IAAI,CA4E9E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOxD"}

package/dist/mcp/index.js

@@ -4142,6 +4142,25 @@ function runMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_usage_log_used_at ON usage_log(used_at);
       `
     },
+    {
+      name: "008_schedules",
+      sql: `
+        CREATE TABLE IF NOT EXISTS prompt_schedules (
+          id TEXT PRIMARY KEY,
+          prompt_id TEXT NOT NULL REFERENCES prompts(id) ON DELETE CASCADE,
+          prompt_slug TEXT NOT NULL,
+          cron TEXT NOT NULL,
+          vars TEXT NOT NULL DEFAULT '{}',
+          agent_id TEXT,
+          last_run_at TEXT,
+          next_run_at TEXT NOT NULL,
+          run_count INTEGER NOT NULL DEFAULT 0,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_prompt_schedules_next_run ON prompt_schedules(next_run_at);
+        CREATE INDEX IF NOT EXISTS idx_prompt_schedules_prompt_id ON prompt_schedules(prompt_id);
+      `
+    },
     {
       name: "002_fts5",
       sql: `
@@ -5137,6 +5156,154 @@ async function maybeSaveMemento(opts) {
   } catch {}
 }
 
+// src/lib/cron.ts
+function parseField(field, min, max) {
+  if (field === "*") {
+    return range(min, max);
+  }
+  const result = [];
+  for (const part of field.split(",")) {
+    if (part.includes("/")) {
+      const [rangeOrStar, stepStr] = part.split("/");
+      const step = parseInt(stepStr ?? "1", 10);
+      const start = rangeOrStar === "*" ? min : parseInt(rangeOrStar ?? String(min), 10);
+      for (let v = start;v <= max; v += step)
+        result.push(v);
+    } else if (part.includes("-")) {
+      const [fromStr, toStr] = part.split("-");
+      const from = parseInt(fromStr ?? String(min), 10);
+      const to = parseInt(toStr ?? String(max), 10);
+      for (let v = from;v <= to; v++)
+        result.push(v);
+    } else {
+      result.push(parseInt(part, 10));
+    }
+  }
+  return [...new Set(result)].sort((a, b) => a - b).filter((v) => v >= min && v <= max);
+}
+function range(min, max) {
+  const r = [];
+  for (let i = min;i <= max; i++)
+    r.push(i);
+  return r;
+}
+function getNextRunTime(cronExpr, from = new Date) {
+  const parts = cronExpr.trim().split(/\s+/);
+  if (parts.length !== 5)
+    throw new Error(`Invalid cron expression (need 5 fields): ${cronExpr}`);
+  const [minField, hourField, domField, monField, dowField] = parts;
+  const minutes = parseField(minField, 0, 59);
+  const hours = parseField(hourField, 0, 23);
+  const doms = parseField(domField, 1, 31);
+  const months = parseField(monField, 1, 12);
+  const dows = parseField(dowField, 0, 6);
+  const next = new Date(from);
+  next.setSeconds(0, 0);
+  next.setMinutes(next.getMinutes() + 1);
+  const limit = new Date(from);
+  limit.setFullYear(limit.getFullYear() + 4);
+  while (next <= limit) {
+    const mon = next.getMonth() + 1;
+    if (!months.includes(mon)) {
+      next.setDate(1);
+      next.setHours(0, 0, 0, 0);
+      next.setMonth(next.getMonth() + 1);
+      continue;
+    }
+    const dom = next.getDate();
+    const dow = next.getDay();
+    const domMatch = domField === "*" || doms.includes(dom);
+    const dowMatch = dowField === "*" || dows.includes(dow);
+    const dayMatch = domField === "*" && dowField === "*" ? true : domField !== "*" && dowField !== "*" ? domMatch || dowMatch : domField !== "*" ? domMatch : dowMatch;
+    if (!dayMatch) {
+      next.setDate(next.getDate() + 1);
+      next.setHours(0, 0, 0, 0);
+      continue;
+    }
+    const h = next.getHours();
+    const validHour = hours.find((v) => v >= h);
+    if (validHour === undefined) {
+      next.setDate(next.getDate() + 1);
+      next.setHours(0, 0, 0, 0);
+      continue;
+    }
+    if (validHour > h) {
+      next.setHours(validHour, 0, 0, 0);
+    }
+    const m = next.getMinutes();
+    const validMin = minutes.find((v) => v >= m);
+    if (validMin === undefined) {
+      next.setHours(next.getHours() + 1, 0, 0, 0);
+      continue;
+    }
+    next.setMinutes(validMin);
+    return next;
+  }
+  throw new Error(`Could not find next run time for cron: ${cronExpr}`);
+}
+function validateCron(expr) {
+  try {
+    getNextRunTime(expr, new Date);
+    return null;
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+}
+
+// src/db/schedules.ts
+function rowToSchedule(row) {
+  return {
+    ...row,
+    vars: JSON.parse(row.vars)
+  };
+}
+function createSchedule(input) {
+  const db = getDatabase();
+  const id = `SCH-${Math.random().toString(36).slice(2, 8).toUpperCase()}`;
+  const next_run_at = getNextRunTime(input.cron).toISOString();
+  const vars = JSON.stringify(input.vars ?? {});
+  db.run(`INSERT INTO prompt_schedules (id, prompt_id, prompt_slug, cron, vars, agent_id, next_run_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [id, input.prompt_id, input.prompt_slug, input.cron, vars, input.agent_id ?? null, next_run_at]);
+  const row = db.query("SELECT * FROM prompt_schedules WHERE id = ?").get(id);
+  return rowToSchedule(row);
+}
+function listSchedules(promptId) {
+  const db = getDatabase();
+  const rows = promptId ? db.query("SELECT * FROM prompt_schedules WHERE prompt_id = ? ORDER BY next_run_at").all(promptId) : db.query("SELECT * FROM prompt_schedules ORDER BY next_run_at").all();
+  return rows.map(rowToSchedule);
+}
+function getSchedule(id) {
+  const db = getDatabase();
+  const row = db.query("SELECT * FROM prompt_schedules WHERE id = ?").get(id);
+  return row ? rowToSchedule(row) : null;
+}
+function deleteSchedule(id) {
+  const db = getDatabase();
+  db.run("DELETE FROM prompt_schedules WHERE id = ?", [id]);
+}
+function getDueSchedules() {
+  const db = getDatabase();
+  const now = new Date().toISOString();
+  const rows = db.query(`SELECT ps.*, p.body as prompt_body
+       FROM prompt_schedules ps
+       JOIN prompts p ON p.id = ps.prompt_id
+       WHERE ps.next_run_at <= ?
+       ORDER BY ps.next_run_at`).all(now);
+  const due = [];
+  for (const row of rows) {
+    const schedule = rowToSchedule(row);
+    let rendered = row.prompt_body;
+    for (const [k, v] of Object.entries(schedule.vars)) {
+      rendered = rendered.replace(new RegExp(`\\{\\{\\s*${k}[^}]*\\}\\}`, "g"), v);
+    }
+    rendered = rendered.replace(/\{\{([^|}]+)\|([^}]*)\}\}/g, (_, _name, def) => def);
+    const newNext = getNextRunTime(schedule.cron).toISOString();
+    db.run(`UPDATE prompt_schedules SET last_run_at = ?, next_run_at = ?, run_count = run_count + 1 WHERE id = ?`, [now, newNext, schedule.id]);
+    due.push({ ...schedule, rendered, prompt_body: row.prompt_body });
+  }
+  return due;
+}
+
 // src/lib/diff.ts
 function diffTexts(a, b) {
   const aLines = a.split(`
@@ -5923,6 +6090,118 @@ server.registerTool("prompts_project_delete", {
     return err(e instanceof Error ? e.message : String(e));
   }
 });
+server.registerTool("prompts_schedule", {
+  description: "Schedule a prompt to run on a cron. Stores the schedule in the DB. Call prompts_get_due periodically (e.g. via /loop) to retrieve and execute due prompts.",
+  inputSchema: {
+    id: exports_external.string().describe("Prompt ID or slug"),
+    cron: exports_external.string().describe("Cron expression (5 fields: min hour dom mon dow). Example: '*/5 * * * *' for every 5 minutes"),
+    vars: exports_external.record(exports_external.string()).optional().describe("Template variable overrides (key\u2192value)"),
+    agent_id: exports_external.string().optional().describe("Agent ID to associate with this schedule")
+  }
+}, async ({ id, cron, vars, agent_id }) => {
+  try {
+    const cronError = validateCron(cron);
+    if (cronError)
+      return err(`Invalid cron expression: ${cronError}`);
+    const prompt = getPrompt(id);
+    if (!prompt)
+      return err(`Prompt not found: ${id}`);
+    const schedule = createSchedule({
+      prompt_id: prompt.id,
+      prompt_slug: prompt.slug,
+      cron,
+      vars,
+      agent_id
+    });
+    return ok({
+      schedule,
+      message: `Prompt "${prompt.title}" scheduled with cron "${cron}". Next run: ${schedule.next_run_at}. Call prompts_get_due to execute due prompts.`
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+});
+server.registerTool("prompts_list_schedules", {
+  description: "List all prompt schedules, optionally filtered by prompt.",
+  inputSchema: {
+    prompt_id: exports_external.string().optional().describe("Filter by prompt ID or slug")
+  }
+}, async ({ prompt_id }) => {
+  try {
+    let resolvedId;
+    if (prompt_id) {
+      const prompt = getPrompt(prompt_id);
+      if (!prompt)
+        return err(`Prompt not found: ${prompt_id}`);
+      resolvedId = prompt.id;
+    }
+    const schedules = listSchedules(resolvedId);
+    return ok({ schedules, count: schedules.length });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+});
+server.registerTool("prompts_unschedule", {
+  description: "Delete a prompt schedule by ID.",
+  inputSchema: { id: exports_external.string().describe("Schedule ID (e.g. SCH-ABC123)") }
+}, async ({ id }) => {
+  try {
+    const schedule = getSchedule(id);
+    if (!schedule)
+      return err(`Schedule not found: ${id}`);
+    deleteSchedule(id);
+    return ok({ deleted: true, id });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+});
+server.registerTool("prompts_get_due", {
+  description: "Get all prompts that are due to run now. Returns the rendered prompt text for each. Automatically advances next_run_at after retrieval. Call this on a loop (e.g. every minute) to drive scheduled prompt execution.",
+  inputSchema: {}
+}, async () => {
+  try {
+    const due = getDueSchedules();
+    if (!due.length)
+      return ok({ due: [], count: 0, message: "No prompts due right now." });
+    return ok({
+      due: due.map((d) => ({
+        schedule_id: d.id,
+        prompt_id: d.prompt_id,
+        prompt_slug: d.prompt_slug,
+        cron: d.cron,
+        rendered: d.rendered,
+        next_run_at: d.next_run_at,
+        run_count: d.run_count
+      })),
+      count: due.length
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+});
+server.registerTool("prompts_next_run", {
+  description: "Preview when a cron expression will next fire, without creating a schedule.",
+  inputSchema: {
+    cron: exports_external.string().describe("Cron expression (5 fields)"),
+    count: exports_external.number().optional().describe("Number of next runs to preview (default: 5)")
+  }
+}, async ({ cron, count = 5 }) => {
+  try {
+    const cronError = validateCron(cron);
+    if (cronError)
+      return err(`Invalid cron expression: ${cronError}`);
+    const runs = [];
+    let from = new Date;
+    for (let i = 0;i < count; i++) {
+      const next = getNextRunTime(cron, from);
+      runs.push(next.toISOString());
+      from = next;
+    }
+    return ok({ cron, next_runs: runs });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+});
 var _agentReg = new Map;
 server.tool("register_agent", "Register this agent session. Returns agent_id for use in heartbeat/set_focus.", { name: exports_external.string(), session_id: exports_external.string().optional() }, async (a) => {
   const existing = [..._agentReg.values()].find((x) => x.name === a.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/prompts",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Reusable prompt library for AI agents — CLI + MCP server + REST API + web dashboard",
   "type": "module",
   "main": "dist/index.js",