my-opencode-toolkit 0.0.0-stage → 0.2.1

package/src/scheduling/index.ts

@@ -0,0 +1,68 @@
+import type { Plugin } from "@opencode/plugin"
+
+import type { SessionRoles } from "../goal/session-role.ts"
+import type { PluginEvent } from "../shared/events.ts"
+import type { ScannableStore } from "../shared/json.ts"
+import { loadSettings } from "../shared/settings-store.ts"
+import type { Disposable } from "../shared/types.ts"
+import { registerSchedulingCommands } from "./command.ts"
+import { createSchedulingContinuation } from "./continuation.ts"
+import type { LoopScheduler } from "./loops.ts"
+import { createLoopScheduler } from "./loops.ts"
+import type { SchedulingStore } from "./store.ts"
+import { createSchedulingStore } from "./store.ts"
+import { registerSchedulingTools } from "./tools.ts"
+
+/** 定时任务功能句柄 + 面板数据源。 */
+export type SchedulingHandle = Disposable & {
+  readonly jobs: SchedulingStore
+  readonly scheduler: LoopScheduler
+  /** 输入：插件事件；输出：无。预期：cron 触发与 loop 状态维护；由外层统一分发。 */
+  handle(event: PluginEvent): Promise<void>
+}
+
+/**
+ * 输入：插件上下文、存储、会话角色、让路回调。
+ * 输出：定时任务功能句柄。
+ * 预期：恢复 durable 任务、注册工具与命令、武装 timer；事件由调用方统一分发。
+ */
+export async function registerScheduling(
+  ctx: Plugin.Context,
+  store: ScannableStore,
+  roles: SessionRoles,
+  shouldDefer: (sessionID: string) => Promise<boolean>,
+): Promise<SchedulingHandle> {
+  const jobs = createSchedulingStore(store)
+  await jobs.load()
+
+  const scheduler = createLoopScheduler({ ctx, roles, shouldDefer })
+  const tools = await registerSchedulingTools(ctx, jobs, scheduler, roles)
+  const commands = await registerSchedulingCommands(ctx, jobs, scheduler, roles)
+
+  const continuation = createSchedulingContinuation({
+    ctx,
+    store: jobs,
+    roles,
+    shouldDefer,
+    enabled: async () => {
+      const settings = await loadSettings(store)
+      return settings.enabled && settings.scheduling.enabled
+    },
+  })
+  continuation.armTimers()
+
+  return {
+    jobs,
+    scheduler,
+    async handle(event) {
+      await continuation.handle(event)
+      await scheduler.handleEvent(event)
+    },
+    async dispose() {
+      continuation.dispose()
+      scheduler.dispose()
+      await tools.dispose()
+      await commands.dispose()
+    },
+  }
+}

package/src/scheduling/loops.ts

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto"
+
+import type { Plugin } from "@opencode/plugin"
+
+import { readEventData } from "../shared/events.ts"
+import { lastMessageIsUserInput } from "../shared/messages.ts"
+import { DEFAULT_MAX_AGE_DAYS, type Loop } from "./types.ts"
+import type { SessionRoles } from "../goal/session-role.ts"
+
+/** 注入消息的 metadata 标记。 */
+const LOOP_MARKER = "loopContinuation"
+
+/** dynamic 模式没有 `schedule_wakeup` 时的兜底唤醒（20 分钟）。 */
+const FALLBACK_WAKEUP_MS = 20 * 60 * 1000
+const WAKEUP_MIN_S = 60
+const WAKEUP_MAX_S = 3600
+
+/** `schedule_wakeup` 的结果。 */
+export type ScheduleWakeupResult =
+  | { readonly ok: true; readonly id: string; readonly fireAt: number }
+  | { readonly ok: false; readonly error: string }
+
+/** 循环调度器。 */
+export type LoopScheduler = {
+  /** 输入：会话 + prompt + 可选间隔；输出：新循环。预期：立即触发一次。 */
+  startLoop(sessionID: string, prompt: string, intervalSeconds?: number): Loop
+  /** 输入：会话 + 可选 id；输出：是否停止。 */
+  stopLoop(sessionID: string, id?: string): boolean
+  /** 输入：会话 + prompt；输出：是否停止。 */
+  stopLoopByPrompt(sessionID: string, prompt: string): boolean
+  /** 输入：会话；输出：停止数量。 */
+  stopAllLoops(sessionID: string): number
+  /** 输入：会话；输出：该会话的循环。 */
+  listLoops(sessionID: string): Loop[]
+  /** 输入：会话 + prompt + 延迟 + 原因；输出：唤醒结果。 */
+  scheduleWakeup(sessionID: string, prompt: string, delaySeconds: number, reason: string): ScheduleWakeupResult
+  /** 输入：会话事件；输出：无。预期：step 结束清 pending，删除会话清循环。 */
+  handleEvent(event: { readonly type: string; readonly data: unknown }): Promise<void>
+  /** 输入：会话；输出：无。预期：停掉该会话全部循环。 */
+  clearSession(sessionID: string): void
+  /** 输入：无；输出：无。预期：清掉所有定时器。 */
+  dispose(): void
+}
+
+/**
+ * 输入：插件上下文、会话角色、是否让路回调。
+ * 输出：循环调度器。
+ * 预期：fixed 按间隔重复，dynamic 等 `schedule_wakeup`，都不给子代理注入。
+ */
+export function createLoopScheduler(args: {
+  readonly ctx: Plugin.Context
+  readonly roles: SessionRoles
+  readonly shouldDefer: (sessionID: string) => Promise<boolean>
+}): LoopScheduler {
+  const { ctx, roles, shouldDefer } = args
+  const loops = new Map<string, Loop>()
+  const timers = new Map<string, ReturnType<typeof setTimeout>>()
+  const inFlight = new Set<string>()
+  const pending = new Set<string>()
+
+  /** 输入：会话 + prompt；输出：匹配的循环。预期：同一 prompt 只保留一个。 */
+  const findLoop = (sessionID: string, prompt: string): Loop | undefined =>
+    [...loops.values()].find((loop) => loop.sessionID === sessionID && loop.prompt === prompt)
+
+  /** 输入：会话 + 文本；输出：是否注入成功。预期：子代理、并发、上一条未完成、末条是用户输入时跳过。 */
+  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, LOOP_MARKER)) return false
+    inFlight.add(sessionID)
+    try {
+      await ctx.session.prompt({ sessionID, text, delivery: "steer", metadata: { [LOOP_MARKER]: true } })
+      pending.add(sessionID)
+      return true
+    } catch {
+      return false
+    } finally {
+      inFlight.delete(sessionID)
+    }
+  }
+
+  /** 输入：循环；输出：无。预期：触发一次注入；过期则停掉。 */
+  const fireLoop = async (loop: Loop): Promise<void> => {
+    if (Date.now() >= loop.expiresAt) {
+      stopLoop(loop.sessionID, loop.id)
+      return
+    }
+    if (await shouldDefer(loop.sessionID)) return
+    loop.fires += 1
+    await inject(loop.sessionID, loop.prompt)
+  }
+
+  /** 输入：循环 + 延迟毫秒；输出：无。预期：重设 timer，`unref` 不阻止进程退出。 */
+  const armLoop = (loop: Loop, delayMs: number): void => {
+    const existing = timers.get(loop.id)
+    if (existing !== undefined) clearTimeout(existing)
+    loop.nextFireAt = Date.now() + delayMs
+    const handle = setTimeout(() => {
+      timers.delete(loop.id)
+      void handleFire(loop)
+    }, Math.max(0, delayMs))
+    handle.unref()
+    timers.set(loop.id, handle)
+  }
+
+  /** 输入：循环；输出：无。预期：触发后按模式决定下一次。 */
+  const handleFire = async (loop: Loop): Promise<void> => {
+    const hadWakeup = loop.pendingWakeup
+    await fireLoop(loop)
+    if (!loops.has(loop.id)) return
+
+    if (loop.mode === "fixed" && loop.intervalSeconds !== undefined) {
+      armLoop(loop, loop.intervalSeconds * 1000)
+      return
+    }
+
+    if (hadWakeup !== undefined) {
+      if (loop.pendingWakeup === hadWakeup) {
+        delete loop.pendingWakeup
+        armLoop(loop, FALLBACK_WAKEUP_MS)
+      }
+      return
+    }
+    if (loop.pendingWakeup !== undefined) return
+    stopLoop(loop.sessionID, loop.id)
+  }
+
+  const startLoop = (sessionID: string, prompt: string, intervalSeconds?: number): Loop => {
+    const existing = findLoop(sessionID, prompt)
+    if (existing !== undefined) stopLoop(sessionID, existing.id)
+
+    const now = Date.now()
+    const loop: Loop = {
+      id: randomUUID().slice(0, 8),
+      sessionID,
+      prompt,
+      mode: intervalSeconds === undefined ? "dynamic" : "fixed",
+      ...(intervalSeconds === undefined ? {} : { intervalSeconds }),
+      createdAt: now,
+      expiresAt: now + DEFAULT_MAX_AGE_DAYS * 24 * 60 * 60 * 1000,
+      fires: 0,
+    }
+    loops.set(loop.id, loop)
+    void fireLoop(loop)
+    armLoop(loop, intervalSeconds === undefined ? FALLBACK_WAKEUP_MS : intervalSeconds * 1000)
+    return loop
+  }
+
+  const stopLoop = (sessionID: string, id?: string): boolean => {
+    const target = id === undefined ? [...loops.values()].find((loop) => loop.sessionID === sessionID) : loops.get(id)
+    if (target?.sessionID !== sessionID) return false
+    const timer = timers.get(target.id)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timers.delete(target.id)
+    }
+    loops.delete(target.id)
+    return true
+  }
+
+  const stopLoopByPrompt = (sessionID: string, prompt: string): boolean => {
+    const loop = findLoop(sessionID, prompt)
+    return loop === undefined ? false : stopLoop(sessionID, loop.id)
+  }
+
+  const stopAllLoops = (sessionID: string): number => {
+    let count = 0
+    for (const loop of [...loops.values()].filter((item) => item.sessionID === sessionID)) {
+      if (stopLoop(sessionID, loop.id)) count += 1
+    }
+    return count
+  }
+
+  const listLoops = (sessionID: string): Loop[] => [...loops.values()].filter((loop) => loop.sessionID === sessionID)
+
+  const scheduleWakeup = (
+    sessionID: string,
+    prompt: string,
+    delaySeconds: number,
+    reason: string,
+  ): ScheduleWakeupResult => {
+    const loop = findLoop(sessionID, prompt)
+    if (loop?.mode !== "dynamic") {
+      return {
+        ok: false,
+        error: "schedule_wakeup is only available inside an active dynamic /loop for this session and prompt.",
+      }
+    }
+    const clamped = Math.min(Math.max(Math.round(delaySeconds), WAKEUP_MIN_S), WAKEUP_MAX_S)
+    const now = Date.now()
+    const fireAt = Math.ceil((now + clamped * 1000) / 60_000) * 60_000
+    loop.pendingWakeup = { fireAt, delaySeconds: clamped, prompt, reason }
+    armLoop(loop, fireAt - now)
+    return { ok: true, id: loop.id, fireAt }
+  }
+
+  const clearSession = (sessionID: string): void => {
+    for (const loop of listLoops(sessionID)) stopLoop(sessionID, loop.id)
+    inFlight.delete(sessionID)
+    pending.delete(sessionID)
+  }
+
+  return {
+    startLoop,
+    stopLoop,
+    stopLoopByPrompt,
+    stopAllLoops,
+    listLoops,
+    scheduleWakeup,
+    clearSession,
+
+    handleEvent(event) {
+      const data = readEventData(event)
+      const sessionID = data?.["sessionID"]
+      if (typeof sessionID !== "string" || sessionID.length === 0) return Promise.resolve()
+
+      if (event.type === "session.deleted") {
+        clearSession(sessionID)
+        return Promise.resolve()
+      }
+      if (event.type === "session.step.ended" || event.type === "session.usage.updated") {
+        pending.delete(sessionID)
+      }
+      return Promise.resolve()
+    },
+
+    dispose() {
+      for (const timer of timers.values()) clearTimeout(timer)
+      timers.clear()
+      loops.clear()
+      inFlight.clear()
+      pending.clear()
+    },
+  }
+}

package/src/scheduling/store.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto"
+
+import { asRecord, type ScannableStore } from "../shared/json.ts"
+import { SCHEDULE_PREFIX, scheduleKey } from "../shared/keys.ts"
+import { forEachScannedEntry } from "../shared/scan.ts"
+import {
+  DEFAULT_CRON_JITTER_CONFIG,
+  jitteredNextCronRunMs,
+  nextCronRunMs,
+  oneShotJitteredNextCronRunMs,
+  parseCronExpression,
+} from "./cron.ts"
+import { JOB_ID_LENGTH, MAX_JOBS, type ScheduledJob } from "./types.ts"
+
+/** 存储格式版本。 */
+const STORE_VERSION = 1
+
+/** 磁盘上的任务形状：没有运行时字段。 */
+type StoredJob = {
+  readonly id: string
+  readonly sessionID: string
+  readonly cron: string
+  readonly prompt: string
+  readonly createdAt: number
+  readonly lastFiredAt?: number
+  readonly recurring?: boolean
+  readonly permanent?: boolean
+}
+
+type StoredFile = {
+  readonly version: number
+  readonly jobs: StoredJob[]
+}
+
+/** 新增任务的输入。 */
+export type AddJobInput = {
+  readonly sessionID: string
+  readonly cron: string
+  readonly prompt: string
+  readonly recurring?: boolean
+  readonly durable?: boolean
+  readonly permanent?: boolean
+}
+
+/** 新增任务的结果。 */
+export type AddJobResult = { ok: true; job: ScheduledJob } | { ok: false; error: string }
+
+/** 定时任务存储。 */
+export type SchedulingStore = {
+  /** 输入：无；输出：无。预期：从存储恢复任务并重建 nextRunAt，幂等。 */
+  load(): Promise<void>
+  /** 输入：任务字段；输出：新任务或错误。预期：校验 cron、匹配性与上限。 */
+  addJob(input: AddJobInput): Promise<AddJobResult>
+  /** 输入：会话 ID（可省）；输出：任务列表。 */
+  listJobs(sessionID?: string): ScheduledJob[]
+  /** 输入：任务 id；输出：任务或 undefined。 */
+  getJob(id: string): ScheduledJob | undefined
+  /** 输入：任务 id 列表；输出：无。预期：删除并同步持久化。 */
+  removeJobs(ids: string[]): Promise<void>
+  /** 输入：任务 id 列表 + 触发时刻；输出：无。预期：recurring 重排下一次。 */
+  markFired(ids: string[], firedAt: number): Promise<void>
+  /** 输入：无；输出：内存中任务总数。 */
+  count(): number
+}
+
+/**
+ * 输入：可扫描存储。
+ * 输出：定时任务存储。
+ * 预期：durable 任务写 `schedule:<sessionID>`；非 durable 只留内存。
+ */
+export function createSchedulingStore(store: ScannableStore): SchedulingStore {
+  const jobs = new Map<string, ScheduledJob>()
+
+  /** 输入：任务；输出：下一次触发毫秒。预期：recurring 带正向抖动，one-shot 带提前量。 */
+  const computeNext = (job: ScheduledJob, fromMs: number): number | null =>
+    job.recurring === true
+      ? jitteredNextCronRunMs(job.cron, fromMs, job.id)
+      : oneShotJitteredNextCronRunMs(job.cron, fromMs, job.id)
+
+  /** 输入：任务；输出：可持久化形状。预期：剥离 durable/nextRunAt 等运行时字段。 */
+  const toStored = (job: ScheduledJob): StoredJob => ({
+    id: job.id,
+    sessionID: job.sessionID,
+    cron: job.cron,
+    prompt: job.prompt,
+    createdAt: job.createdAt,
+    ...(job.lastFiredAt === undefined ? {} : { lastFiredAt: job.lastFiredAt }),
+    ...(job.recurring === true ? { recurring: true } : {}),
+    ...(job.permanent === true ? { permanent: true } : {}),
+  })
+
+  /** 输入：会话 ID；输出：无。预期：只写 durable 任务；没有 durable 任务时删 key。 */
+  const persist = async (sessionID: string): Promise<void> => {
+    const durable = [...jobs.values()].filter((job) => job.sessionID === sessionID && job.durable !== false)
+    if (durable.length === 0) {
+      await store.remove(scheduleKey(sessionID))
+      return
+    }
+    const file: StoredFile = { version: STORE_VERSION, jobs: durable.map(toStored) }
+    await store.set(scheduleKey(sessionID), file)
+  }
+
+  /** 输入：任意值；输出：合法任务或 null。预期：跳过字段缺失/类型错误的条目。 */
+  const parseStored = (value: unknown): StoredJob | null => {
+    const record = asRecord(value)
+    if (record === undefined) return null
+    const { id, sessionID, cron, prompt, createdAt } = record
+    if (typeof id !== "string" || id.length === 0) return null
+    if (typeof sessionID !== "string" || sessionID.length === 0) return null
+    if (typeof cron !== "string" || parseCronExpression(cron) === null) return null
+    if (typeof prompt !== "string") return null
+    if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) return null
+    const lastFiredAt = record["lastFiredAt"]
+    return {
+      id,
+      sessionID,
+      cron,
+      prompt,
+      createdAt,
+      ...(typeof lastFiredAt === "number" && Number.isFinite(lastFiredAt) ? { lastFiredAt } : {}),
+      ...(record["recurring"] === true ? { recurring: true } : {}),
+      ...(record["permanent"] === true ? { permanent: true } : {}),
+    }
+  }
+
+  return {
+    async load() {
+      await forEachScannedEntry(store, SCHEDULE_PREFIX, (entry) => {
+        const record = asRecord(entry.value)
+        if (record === undefined) return Promise.resolve()
+        const rawJobs = record["jobs"]
+        if (!Array.isArray(rawJobs)) return Promise.resolve()
+
+        for (const raw of rawJobs) {
+          const stored = parseStored(raw)
+          if (stored === null) continue
+          const job: ScheduledJob = { ...stored, durable: true }
+          const next = computeNext(job, job.lastFiredAt ?? job.createdAt)
+          if (next !== null) job.nextRunAt = next
+          jobs.set(job.id, job)
+        }
+        return Promise.resolve()
+      })
+    },
+
+    async addJob(input) {
+      const { sessionID, cron, prompt, recurring = false, durable = false, permanent = false } = input
+      if (parseCronExpression(cron) === null) {
+        return { ok: false, error: `Invalid cron expression '${cron}'. Expected 5 fields: M H DoM Mon DoW.` }
+      }
+      if (nextCronRunMs(cron, Date.now()) === null) {
+        return { ok: false, error: `Cron expression '${cron}' does not match any calendar date in the next year.` }
+      }
+      const sessionJobs = [...jobs.values()].filter((job) => job.sessionID === sessionID).length
+      if (sessionJobs >= MAX_JOBS) {
+        return { ok: false, error: `Too many scheduled jobs (max ${String(MAX_JOBS)} per session). Cancel one first.` }
+      }
+
+      const now = Date.now()
+      const job: ScheduledJob = {
+        id: randomUUID().slice(0, JOB_ID_LENGTH),
+        sessionID,
+        cron,
+        prompt,
+        createdAt: now,
+        ...(recurring ? { recurring: true } : {}),
+        ...(permanent ? { permanent: true } : {}),
+        durable,
+      }
+      const next = computeNext(job, now)
+      if (next !== null) job.nextRunAt = next
+      jobs.set(job.id, job)
+      if (durable) await persist(sessionID)
+      return { ok: true, job }
+    },
+
+    listJobs(sessionID) {
+      const all = [...jobs.values()]
+      return sessionID === undefined ? all : all.filter((job) => job.sessionID === sessionID)
+    },
+
+    getJob(id) {
+      return jobs.get(id)
+    },
+
+    async removeJobs(ids) {
+      const touched = new Set<string>()
+      for (const id of ids) {
+        const job = jobs.get(id)
+        if (job === undefined) continue
+        touched.add(job.sessionID)
+        jobs.delete(id)
+      }
+      for (const sessionID of touched) await persist(sessionID)
+    },
+
+    async markFired(ids, firedAt) {
+      const touched = new Set<string>()
+      for (const id of ids) {
+        const job = jobs.get(id)
+        if (job?.recurring !== true) continue
+        touched.add(job.sessionID)
+        job.lastFiredAt = firedAt
+        const next = computeNext(job, firedAt)
+        if (next !== null) job.nextRunAt = next
+      }
+      for (const sessionID of touched) await persist(sessionID)
+    },
+
+    count() {
+      return jobs.size
+    },
+  }
+}
+
+/**
+ * 输入：任务 + 当前时刻。
+ * 输出：是否已过 7 天自动过期。
+ * 预期：one-shot、permanent 与 `maxAgeMs === 0` 都不过期。
+ */
+export function isRecurringTaskAged(
+  task: ScheduledJob,
+  nowMs: number,
+  maxAgeMs: number = DEFAULT_CRON_JITTER_CONFIG.recurringMaxAgeMs,
+): boolean {
+  if (maxAgeMs === 0) return false
+  return task.recurring === true && task.permanent !== true && nowMs - task.createdAt >= maxAgeMs
+}