my-opencode-toolkit 0.0.0-stage → 0.2.1

package/src/scheduling/command.ts

@@ -0,0 +1,181 @@
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import type { Plugin } from "@opencode/plugin"
+
+import type { SessionRoles } from "../goal/session-role.ts"
+import { loadSettings } from "../shared/settings-store.ts"
+import type { LoopScheduler } from "./loops.ts"
+import type { SchedulingStore } from "./store.ts"
+import { cronToHuman } from "./cron.ts"
+
+/** 内置维护提示词（没有 `loop.md` 时的默认）。 */
+export const DEFAULT_LOOP_MAINTENANCE_PROMPT =
+  "Continue unfinished work in this session. Re-read AGENTS.md and progress files, pick the next concrete step, " +
+  "and keep going. Run cleanup passes when appropriate."
+
+/** `/loop` 解析结果。 */
+export type LoopCommand =
+  | { readonly kind: "start"; readonly prompt: string; readonly intervalSeconds?: number }
+  | { readonly kind: "stop" }
+
+/**
+ * 输入：`5m` / `30s` / `2h` / `1d` 形式。
+ * 输出：秒数（秒向上取整到分钟，最小 60），非法返回 undefined。
+ */
+export function parseIntervalSeconds(value: string): number | undefined {
+  const match = /^(\d+)([smhd])$/.exec(value)
+  if (match === null) return undefined
+  const amount = Number.parseInt(match[1] ?? "", 10)
+  const unit = match[2]
+  if (!Number.isFinite(amount) || amount <= 0) return undefined
+  switch (unit) {
+    case "s":
+      return Math.max(60, Math.ceil(amount / 60) * 60)
+    case "m":
+      return amount * 60
+    case "h":
+      return amount * 3600
+    case "d":
+      return amount * 86400
+    default:
+      return undefined
+  }
+}
+
+/**
+ * 输入：`/loop` 参数。
+ * 输出：停止，或带可选固定间隔的启动参数。
+ * 预期：首个 token 是合法间隔则剥离，剩余为 prompt；`stop` 单独处理。
+ */
+export function parseLoopCommand(rawArgs: string): LoopCommand {
+  const trimmed = rawArgs.trim()
+  if (trimmed.toLowerCase() === "stop") return { kind: "stop" }
+  const parts = trimmed.split(/\s+/)
+  const first = parts[0]
+  if (first === undefined || first === "") return { kind: "start", prompt: "" }
+
+  const intervalSeconds = parseIntervalSeconds(first)
+  if (intervalSeconds === undefined) return { kind: "start", prompt: trimmed }
+  return { kind: "start", prompt: parts.slice(1).join(" ").trim(), intervalSeconds }
+}
+
+/** 输入：项目目录；输出：维护提示词。预期：`loop.md` 非空时优先。 */
+async function loadMaintenancePrompt(directory: string | undefined): Promise<string> {
+  if (directory === undefined) return DEFAULT_LOOP_MAINTENANCE_PROMPT
+  try {
+    const raw = (await readFile(join(directory, "loop.md"), "utf8")).trim()
+    return raw.length > 0 ? raw : DEFAULT_LOOP_MAINTENANCE_PROMPT
+  } catch {
+    return DEFAULT_LOOP_MAINTENANCE_PROMPT
+  }
+}
+
+/**
+ * 输入：`/cron` 参数。
+ * 输出：`{ expr, prompt }` 或错误文本。
+ * 预期：前 5 个 token 是 cron 表达式，剩余为 prompt。
+ */
+function splitCron(rest: string): { expr: string; prompt: string } | null {
+  const parts = rest.trim().split(/\s+/)
+  if (parts.length < 6) return null
+  return { expr: parts.slice(0, 5).join(" "), prompt: parts.slice(5).join(" ") }
+}
+
+/**
+ * 输入：插件上下文、任务存储、循环调度器、会话角色。
+ * 输出：注册 `/loop` 与 `/cron` 命令。
+ * 预期：命令自身不进对话流；执行结果作为普通 prompt 发回当前会话。
+ */
+export async function registerSchedulingCommands(
+  ctx: Plugin.Context,
+  store: SchedulingStore,
+  scheduler: LoopScheduler,
+  roles: SessionRoles,
+): Promise<{ dispose(): Promise<void> }> {
+  /** 输入：会话 ID；输出：不可用原因，可用时为 null。 */
+  const unavailable = async (sessionID: string): Promise<string | null> => {
+    const settings = await loadSettings(ctx.storage)
+    if (!settings.enabled || !settings.scheduling.enabled) return "Error: the scheduling feature is disabled in settings."
+    if (await roles.isSubagent(sessionID)) return "Error: scheduling commands are not available to subagents."
+    return null
+  }
+
+  const registration = await ctx.command.transform((editor) => {
+    editor.add({
+      name: "loop",
+      description: "Start or stop a recurring prompt loop in this session",
+      execute: async (input) => {
+        const blocked = await unavailable(input.sessionID)
+        const parsed = parseLoopCommand(input.prompt.text)
+        const text = await (async (): Promise<string> => {
+          if (blocked !== null) return blocked
+          if (parsed.kind === "stop") {
+            const count = scheduler.stopAllLoops(input.sessionID)
+            return count === 0 ? "No active loop." : `Stopped ${String(count)} loop(s).`
+          }
+          const prompt = parsed.prompt.length > 0 ? parsed.prompt : await loadMaintenancePrompt(ctx.location.directory)
+          const loop = scheduler.startLoop(input.sessionID, prompt, parsed.intervalSeconds)
+          return loop.mode === "fixed"
+            ? `Loop ${loop.id} started: every ${String(loop.intervalSeconds ?? 0)}s — ${prompt}`
+            : `Loop ${loop.id} started (dynamic): ${prompt}`
+        })()
+        await ctx.session.prompt({ sessionID: input.sessionID, text, delivery: input.delivery })
+      },
+    })
+
+    editor.add({
+      name: "cron",
+      description: "Create, list or delete scheduled prompts for this session",
+      execute: async (input) => {
+        const blocked = await unavailable(input.sessionID)
+        const raw = input.prompt.text.trim()
+        const text = await (async (): Promise<string> => {
+          if (blocked !== null) return blocked
+
+          if (raw === "" || raw.toLowerCase() === "list") {
+            const jobs = store.listJobs(input.sessionID)
+            if (jobs.length === 0) return "No scheduled jobs."
+            return jobs
+              .map((job) => {
+                const kind = job.recurring === true ? "recurring" : "one-shot"
+                return `${job.id} — ${cronToHuman(job.cron)} (${kind}): ${job.prompt}`
+              })
+              .join("\n")
+          }
+
+          const deleteMatch = /^delete\s+(\S+)$/i.exec(raw)
+          if (deleteMatch !== null) {
+            const id = deleteMatch[1] ?? ""
+            const job = store.getJob(id)
+            if (job === undefined) return `Error: No scheduled job with id '${id}'`
+            if (job.sessionID !== input.sessionID) return `Error: Cannot delete cron job '${id}': owned by another session`
+            await store.removeJobs([id])
+            return `Cancelled job ${id}.`
+          }
+
+          const once = /^once\s+(.+)$/is.exec(raw)
+          const body = once === null ? raw : (once[1] ?? "")
+          const split = splitCron(body)
+          if (split === null) return "Usage: /cron <expr> <prompt> | /cron once <expr> <prompt> | /cron list | /cron delete <id>"
+
+          const result = await store.addJob({
+            sessionID: input.sessionID,
+            cron: split.expr,
+            prompt: split.prompt,
+            recurring: once === null,
+            durable: true,
+          })
+          if (!result.ok) return `Error: ${result.error}`
+          const job = result.job
+          return job.recurring === true
+            ? `Scheduled recurring job ${job.id} (${cronToHuman(job.cron)}): ${job.prompt}`
+            : `Scheduled one-shot task ${job.id} (${cronToHuman(job.cron)}): ${job.prompt}`
+        })()
+        await ctx.session.prompt({ sessionID: input.sessionID, text, delivery: input.delivery })
+      },
+    })
+  })
+  await ctx.command.reload()
+  return registration
+}

package/src/scheduling/continuation.ts

@@ -0,0 +1,164 @@
+import type { Plugin } from "@opencode/plugin"
+
+import { readEventData } from "../shared/events.ts"
+import { lastMessageIsUserInput } from "../shared/messages.ts"
+import type { SessionRoles } from "../goal/session-role.ts"
+import type { SchedulingStore } from "./store.ts"
+import { isRecurringTaskAged } from "./store.ts"
+import type { ScheduledJob } from "./types.ts"
+
+/** 注入消息的 metadata 标记。 */
+const CRON_MARKER = "cronContinuation"
+
+/** 定时任务触发控制器。 */
+export type SchedulingContinuation = {
+  /** 输入：会话事件；输出：无。预期：idle 兜底触发，删除会话清任务。 */
+  handle(event: { readonly type: string; readonly data: unknown }): Promise<void>
+  /** 输入：无；输出：无。预期：给所有未来任务武装 timer。 */
+  armTimers(): void
+  /** 输入：无；输出：无。预期：清掉全部 timer。 */
+  dispose(): void
+}
+
+/**
+ * 输入：时间。
+ * 输出：`Nov 3 2:30pm` 形式的英文时间。
+ * 预期：只用于注入文本，固定 en-US 以免跟随系统语言变化。
+ */
+function formatFireTime(date: Date): string {
+  return date
+    .toLocaleString("en-US", { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" })
+    .replace(/,? at |, /, " ")
+    .replace(/ ([AP]M)/, (_, ampm: string) => ampm.toLowerCase())
+}
+
+/** 输入：任务 + 触发时间；输出：注入文本。 */
+function buildFirePrompt(job: ScheduledJob, at: Date): string {
+  return `Running scheduled task (${formatFireTime(at)})\n\n${job.prompt}`
+}
+
+/**
+ * 输入：插件上下文、存储、会话角色、让路回调、启用判断。
+ * 输出：定时任务触发控制器。
+ * 预期：到点先无条件重排/删除，再尽力注入；子代理与让路时不注入。
+ */
+export function createSchedulingContinuation(args: {
+  readonly ctx: Plugin.Context
+  readonly store: SchedulingStore
+  readonly roles: SessionRoles
+  readonly shouldDefer: (sessionID: string) => Promise<boolean>
+  readonly enabled: () => Promise<boolean>
+  readonly now?: () => number
+}): SchedulingContinuation {
+  const { ctx, store, roles, shouldDefer, enabled } = args
+  const now = args.now ?? Date.now
+  const timers = new Map<string, ReturnType<typeof setTimeout>>()
+  const inFlight = new Set<string>()
+  const pending = new Set<string>()
+
+  /** 输入：会话 + 文本；输出：是否注入成功。预期：并发、上一条未完成或末条是用户输入时跳过。 */
+  const inject = async (sessionID: string, text: string): Promise<boolean> => {
+    if (inFlight.has(sessionID) || pending.has(sessionID)) return false
+    if (await roles.isSubagent(sessionID)) return false
+    if (await lastMessageIsUserInput(ctx, sessionID, CRON_MARKER)) return false
+    inFlight.add(sessionID)
+    try {
+      await ctx.session.prompt({ sessionID, text, delivery: "steer", metadata: { [CRON_MARKER]: true } })
+      pending.add(sessionID)
+      return true
+    } catch {
+      return false
+    } finally {
+      inFlight.delete(sessionID)
+    }
+  }
+
+  /** 输入：无；输出：无。预期：每个未来任务一个 timer，已有 timer 的不重复武装。 */
+  const armTimers = (): void => {
+    const at = now()
+    for (const job of store.listJobs()) {
+      if (job.nextRunAt === undefined || timers.has(job.id)) continue
+      const delay = job.nextRunAt - at
+      if (delay <= 0) continue
+      const handle = setTimeout(() => {
+        timers.delete(job.id)
+        const fresh = store.getJob(job.id)
+        if (fresh !== undefined) void handleCronFire(fresh)
+      }, delay)
+      handle.unref()
+      timers.set(job.id, handle)
+    }
+  }
+
+  /** 输入：任务；输出：无。预期：先重排/删除，再判断是否注入。 */
+  const handleCronFire = async (job: ScheduledJob): Promise<void> => {
+    const at = now()
+    const aged = isRecurringTaskAged(job, at)
+    if (aged || job.recurring !== true) {
+      await store.removeJobs([job.id])
+    } else {
+      await store.markFired([job.id], at)
+    }
+    armTimers()
+
+    if (!(await enabled())) return
+    if (await shouldDefer(job.sessionID)) return
+    await inject(job.sessionID, buildFirePrompt(job, new Date(at)))
+  }
+
+  /** 输入：会话 ID；输出：无。预期：处理该会话已到点的任务，否则补武装 timer。 */
+  const handleIdle = async (sessionID: string): Promise<void> => {
+    if (!(await enabled())) return
+    const at = now()
+    const due = store
+      .listJobs(sessionID)
+      .filter((job) => job.nextRunAt !== undefined && job.nextRunAt <= at)
+      .sort((a, b) => (a.nextRunAt ?? Number.POSITIVE_INFINITY) - (b.nextRunAt ?? Number.POSITIVE_INFINITY))
+    const job = due[0]
+    if (job !== undefined) {
+      await handleCronFire(job)
+      return
+    }
+    armTimers()
+  }
+
+  return {
+    async handle(event) {
+      const data = readEventData(event)
+      const sessionID = data?.["sessionID"]
+      if (typeof sessionID !== "string" || sessionID.length === 0) return
+
+      if (event.type === "session.idle") {
+        await handleIdle(sessionID)
+        return
+      }
+      if (event.type === "session.deleted") {
+        const ids = store.listJobs(sessionID).map((job) => job.id)
+        for (const id of ids) {
+          const timer = timers.get(id)
+          if (timer !== undefined) {
+            clearTimeout(timer)
+            timers.delete(id)
+          }
+        }
+        await store.removeJobs(ids)
+        inFlight.delete(sessionID)
+        pending.delete(sessionID)
+        roles.forget(sessionID)
+        return
+      }
+      if (event.type === "session.step.ended" || event.type === "session.usage.updated") {
+        pending.delete(sessionID)
+      }
+    },
+
+    armTimers,
+
+    dispose() {
+      for (const timer of timers.values()) clearTimeout(timer)
+      timers.clear()
+      inFlight.clear()
+      pending.clear()
+    },
+  }
+}

package/src/scheduling/cron.ts

@@ -0,0 +1,309 @@
+/** 展开后的 5 个 cron 字段。 */
+export type CronFields = {
+  minute: number[]
+  hour: number[]
+  dayOfMonth: number[]
+  month: number[]
+  dayOfWeek: number[]
+}
+
+type FieldRange = { min: number; max: number }
+
+const FIELD_RANGES: readonly FieldRange[] = [
+  { min: 0, max: 59 }, // minute
+  { min: 0, max: 23 }, // hour
+  { min: 1, max: 31 }, // dayOfMonth
+  { min: 1, max: 12 }, // month
+  { min: 0, max: 6 }, // dayOfWeek（7 也接受为周日）
+]
+
+/**
+ * 输入：单个 cron 字段 + 取值范围。
+ * 输出：升序匹配值数组，非法返回 `null`。
+ * 预期：支持通配、步进（`*` 后跟斜杠与数字）、单值、范围、范围步进、逗号列表；dayOfWeek 的 7 归一成 0。
+ */
+function expandField(field: string, range: FieldRange): number[] | null {
+  const { min, max } = range
+  const out = new Set<number>()
+
+  for (const part of field.split(",")) {
+    const stepMatch = /^\*(?:\/(\d+))?$/.exec(part)
+    if (stepMatch !== null) {
+      const step = stepMatch[1] === undefined ? 1 : Number.parseInt(stepMatch[1], 10)
+      if (step < 1) return null
+      for (let i = min; i <= max; i += step) out.add(i)
+      continue
+    }
+
+    const rangeMatch = /^(\d+)-(\d+)(?:\/(\d+))?$/.exec(part)
+    if (rangeMatch !== null) {
+      const lo = Number.parseInt(rangeMatch[1] ?? "", 10)
+      const hi = Number.parseInt(rangeMatch[2] ?? "", 10)
+      const step = rangeMatch[3] === undefined ? 1 : Number.parseInt(rangeMatch[3], 10)
+      // dayOfWeek: 范围里 7 作为周日别名（5-7 → [5,6,0]）
+      const isDow = min === 0 && max === 6
+      const effMax = isDow ? 7 : max
+      if (lo > hi || step < 1 || lo < min || hi > effMax) return null
+      for (let i = lo; i <= hi; i += step) out.add(isDow && i === 7 ? 0 : i)
+      continue
+    }
+
+    if (/^\d+$/.test(part)) {
+      let n = Number.parseInt(part, 10)
+      if (min === 0 && max === 6 && n === 7) n = 0
+      if (n < min || n > max) return null
+      out.add(n)
+      continue
+    }
+
+    return null
+  }
+
+  if (out.size === 0) return null
+  return Array.from(out).sort((a, b) => a - b)
+}
+
+/**
+ * 输入：5 字段 cron（本地时区，`minute hour dayOfMonth month dayOfWeek`）。
+ * 输出：展开后的字段，非法返回 `null`。
+ */
+export function parseCronExpression(expr: string): CronFields | null {
+  const parts = expr.trim().split(/\s+/)
+  if (parts.length !== 5) return null
+
+  const expanded: number[][] = []
+  for (const [index, part] of parts.entries()) {
+    const range = FIELD_RANGES[index]
+    if (range === undefined) return null
+    const result = expandField(part, range)
+    if (result === null) return null
+    expanded.push(result)
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = expanded
+  if (
+    minute === undefined ||
+    hour === undefined ||
+    dayOfMonth === undefined ||
+    month === undefined ||
+    dayOfWeek === undefined
+  ) {
+    return null
+  }
+  return { minute, hour, dayOfMonth, month, dayOfWeek }
+}
+
+/**
+ * 输入：展开后的字段 + 起点时间。
+ * 输出：严格晚于起点、第一个匹配的本地时刻，一年内无匹配返回 `null`。
+ * 预期：dayOfMonth 与 dayOfWeek 都受限时任一匹配即可（OR 语义）。
+ */
+export function computeNextCronRun(fields: CronFields, from: Date): Date | null {
+  const minuteSet = new Set(fields.minute)
+  const hourSet = new Set(fields.hour)
+  const domSet = new Set(fields.dayOfMonth)
+  const monthSet = new Set(fields.month)
+  const dowSet = new Set(fields.dayOfWeek)
+
+  const domWild = fields.dayOfMonth.length === 31
+  const dowWild = fields.dayOfWeek.length === 7
+
+  const t = new Date(from.getTime())
+  t.setSeconds(0, 0)
+  t.setMinutes(t.getMinutes() + 1)
+
+  const maxIter = 366 * 24 * 60
+  for (let i = 0; i < maxIter; i += 1) {
+    if (!monthSet.has(t.getMonth() + 1)) {
+      t.setMonth(t.getMonth() + 1, 1)
+      t.setHours(0, 0, 0, 0)
+      continue
+    }
+
+    const dayMatches =
+      domWild && dowWild
+        ? true
+        : domWild
+          ? dowSet.has(t.getDay())
+          : dowWild
+            ? domSet.has(t.getDate())
+            : domSet.has(t.getDate()) || dowSet.has(t.getDay())
+
+    if (!dayMatches) {
+      t.setDate(t.getDate() + 1)
+      t.setHours(0, 0, 0, 0)
+      continue
+    }
+
+    if (!hourSet.has(t.getHours())) {
+      t.setHours(t.getHours() + 1, 0, 0, 0)
+      continue
+    }
+
+    if (!minuteSet.has(t.getMinutes())) {
+      t.setMinutes(t.getMinutes() + 1)
+      continue
+    }
+
+    return t
+  }
+
+  return null
+}
+
+/**
+ * 输入：cron 字符串 + 起点毫秒。
+ * 输出：下一次触发毫秒，非法或无匹配返回 `null`。
+ */
+export function nextCronRunMs(cron: string, fromMs: number): number | null {
+  const fields = parseCronExpression(cron)
+  if (fields === null) return null
+  return computeNextCronRun(fields, new Date(fromMs))?.getTime() ?? null
+}
+
+/** cron 的人类可读描述（英文）。 */
+export type CronHuman =
+  | { kind: "every_minute"; n: number }
+  | { kind: "every_hour"; minute: number }
+  | { kind: "every_n_hours"; n: number; minute: number }
+  | { kind: "daily"; hour: number; minute: number }
+  | { kind: "weekly"; day: number; hour: number; minute: number }
+  | { kind: "weekdays"; hour: number; minute: number }
+  | { kind: "raw"; text: string }
+
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
+
+/**
+ * 输入：cron 字符串。
+ * 输出：常见模式的结构化描述，无法识别时回退 `raw`。
+ */
+function parseCronHuman(cron: string): CronHuman {
+  const parts = cron.trim().split(/\s+/)
+  if (parts.length !== 5) return { kind: "raw", text: cron }
+  const [minute = "", hour = "", dayOfMonth = "", month = "", dayOfWeek = ""] = parts
+
+  const everyMin = /^\*\/(\d+)$/.exec(minute)
+  if (everyMin !== null && hour === "*" && dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+    return { kind: "every_minute", n: Number.parseInt(everyMin[1] ?? "1", 10) }
+  }
+
+  if (/^\d+$/.test(minute) && hour === "*" && dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+    return { kind: "every_hour", minute: Number.parseInt(minute, 10) }
+  }
+
+  const everyHour = /^\*\/(\d+)$/.exec(hour)
+  if (/^\d+$/.test(minute) && everyHour !== null && dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+    return {
+      kind: "every_n_hours",
+      n: Number.parseInt(everyHour[1] ?? "1", 10),
+      minute: Number.parseInt(minute, 10),
+    }
+  }
+
+  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return { kind: "raw", text: cron }
+  const m = Number.parseInt(minute, 10)
+  const h = Number.parseInt(hour, 10)
+
+  if (dayOfMonth === "*" && month === "*" && dayOfWeek === "*") return { kind: "daily", hour: h, minute: m }
+  if (dayOfMonth === "*" && month === "*" && /^\d$/.test(dayOfWeek)) {
+    return { kind: "weekly", day: Number.parseInt(dayOfWeek, 10) % 7, hour: h, minute: m }
+  }
+  if (dayOfMonth === "*" && month === "*" && dayOfWeek === "1-5") return { kind: "weekdays", hour: h, minute: m }
+
+  return { kind: "raw", text: cron }
+}
+
+/** 输入：小时 + 分钟；输出：`HH:MM`。预期：固定两位，便于工具输出。 */
+function formatTime(hour: number, minute: number): string {
+  return `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`
+}
+
+/**
+ * 输入：cron 字符串。
+ * 输出：英文人类可读描述（给模型看的工具输出）。
+ */
+export function cronToHuman(cron: string): string {
+  const human = parseCronHuman(cron)
+  switch (human.kind) {
+    case "every_minute":
+      return human.n === 1 ? "every minute" : `every ${String(human.n)} minutes`
+    case "every_hour":
+      return human.minute === 0 ? "every hour" : `every hour at :${String(human.minute).padStart(2, "0")}`
+    case "every_n_hours":
+      return `every ${String(human.n)} hours at :${String(human.minute).padStart(2, "0")}`
+    case "daily":
+      return `daily at ${formatTime(human.hour, human.minute)}`
+    case "weekly":
+      return `weekly on ${DAY_NAMES[human.day] ?? String(human.day)} at ${formatTime(human.hour, human.minute)}`
+    case "weekdays":
+      return `weekdays at ${formatTime(human.hour, human.minute)}`
+    case "raw":
+      return human.text
+  }
+}
+
+/** jitter 参数。 */
+export type CronJitterConfig = {
+  readonly recurringFrac: number
+  readonly recurringCapMs: number
+  readonly oneShotMaxMs: number
+  readonly oneShotFloorMs: number
+  readonly oneShotMinuteMod: number
+  readonly recurringMaxAgeMs: number
+}
+
+export const DEFAULT_CRON_JITTER_CONFIG: CronJitterConfig = {
+  recurringFrac: 0.1,
+  recurringCapMs: 15 * 60 * 1000,
+  oneShotMaxMs: 90 * 1000,
+  oneShotFloorMs: 0,
+  oneShotMinuteMod: 30,
+  recurringMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
+}
+
+/**
+ * 输入：任务 id。
+ * 输出：`[0,1)` 的稳定分数。
+ * 预期：非 hex id 回退 0（无抖动）。
+ */
+function jitterFrac(taskId: string): number {
+  const frac = Number.parseInt(taskId.slice(0, 8), 16) / 0x1_0000_0000
+  return Number.isFinite(frac) ? frac : 0
+}
+
+/**
+ * 输入：cron + 起点 + 任务 id。
+ * 输出：带确定性正向延迟的下一次触发时刻（recurring 用）。
+ * 预期：延迟不超过间隔的 10%，且不超过 15 分钟；没有第二跳时不抖。
+ */
+export function jitteredNextCronRunMs(
+  cron: string,
+  fromMs: number,
+  taskId: string,
+  cfg: CronJitterConfig = DEFAULT_CRON_JITTER_CONFIG,
+): number | null {
+  const first = nextCronRunMs(cron, fromMs)
+  if (first === null) return null
+  const second = nextCronRunMs(cron, first)
+  if (second === null) return first
+  const jitter = Math.min(jitterFrac(taskId) * cfg.recurringFrac * (second - first), cfg.recurringCapMs)
+  return first + jitter
+}
+
+/**
+ * 输入：cron + 起点 + 任务 id。
+ * 输出：带确定性提前量的下一次触发时刻（one-shot 用）。
+ * 预期：只在分钟命中 `oneShotMinuteMod` 时提前，且不早于起点。
+ */
+export function oneShotJitteredNextCronRunMs(
+  cron: string,
+  fromMs: number,
+  taskId: string,
+  cfg: CronJitterConfig = DEFAULT_CRON_JITTER_CONFIG,
+): number | null {
+  const first = nextCronRunMs(cron, fromMs)
+  if (first === null) return null
+  if (new Date(first).getMinutes() % cfg.oneShotMinuteMod !== 0) return first
+  const lead = cfg.oneShotFloorMs + jitterFrac(taskId) * (cfg.oneShotMaxMs - cfg.oneShotFloorMs)
+  return Math.max(first - lead, fromMs)
+}

package/src/scheduling/filter.ts

@@ -0,0 +1,25 @@
+/**
+ * 输入：即将发给模型的工具表（会被原地修改）。
+ * 输出：实际删掉的工具名。
+ * 预期：只删 scheduling 工具，其余工具原样保留；不存在时跳过。
+ */
+export function hideSchedulingTools(tools: Record<string, unknown>): string[] {
+  const removed: string[] = []
+  if ("cron_create" in tools) {
+    delete tools["cron_create"]
+    removed.push("cron_create")
+  }
+  if ("cron_list" in tools) {
+    delete tools["cron_list"]
+    removed.push("cron_list")
+  }
+  if ("cron_delete" in tools) {
+    delete tools["cron_delete"]
+    removed.push("cron_delete")
+  }
+  if ("schedule_wakeup" in tools) {
+    delete tools["schedule_wakeup"]
+    removed.push("schedule_wakeup")
+  }
+  return removed
+}