@zhushanwen/pi-scheduler 0.0.2

package/src/runtime.ts

@@ -0,0 +1,253 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+
+import { autoName, generateTaskId } from './format.js'
+import { computeNextCronRunAt, parseDuration } from './parsing.js'
+import { createStore } from './store.js'
+import type { AddOptions, ScheduledTask, SchedulerStore, ScheduleSpec } from './types.js'
+
+const MAX_TASKS = 50
+const RATE_LIMIT_PER_MINUTE = 6
+const TICK_INTERVAL_MS = 30_000
+const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+export class SchedulerRuntime {
+  private tasks: Map<string, ScheduledTask> = new Map()
+  private store: ReturnType<typeof createStore>
+  private pi: Pick<ExtensionAPI, 'sendMessage'>
+  private ctx: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>
+  private tickTimer: ReturnType<typeof setInterval> | null = null
+  private dispatchTimestamps: number[] = []
+
+  constructor(
+    cwd: string,
+    pi: Pick<ExtensionAPI, 'sendMessage'>,
+    ctx: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>,
+  ) {
+    this.store = createStore(cwd)
+    this.pi = pi
+    this.ctx = ctx
+  }
+
+  // ── 任务 CRUD ──
+
+  async addTask(prompt: string, schedule: ScheduleSpec, options: AddOptions = {}): Promise<ScheduledTask> {
+    if (this.tasks.size >= MAX_TASKS) {
+      throw new Error(`Task limit reached (${MAX_TASKS}). Delete a task first.`)
+    }
+
+    const id = generateTaskId()
+    const now = Date.now()
+    const kind = options.kind ?? 'recurring'
+    const name = options.name ?? autoName(prompt)
+
+    let expiresAt: number | undefined
+    if (options.expires === 'never') {
+      expiresAt = undefined
+    } else if (kind === 'recurring') {
+      const expiryMs = options.expires ? (parseDuration(options.expires) ?? DEFAULT_EXPIRY_MS) : DEFAULT_EXPIRY_MS
+      expiresAt = now + expiryMs
+    }
+
+    // 计算 nextRunAt：interval 模式 now + intervalMs；cron 模式首跑时间
+    let nextRunAt: number
+    if (schedule.mode === 'interval') {
+      nextRunAt = now + schedule.intervalMs
+    } else {
+      const next = await computeNextCronRunAt(schedule.cronExpression, now)
+      if (next === undefined) {
+        throw new Error(`Invalid cron expression: ${schedule.cronExpression}`)
+      }
+      nextRunAt = next
+    }
+
+    const task: ScheduledTask = {
+      id,
+      name,
+      prompt,
+      kind,
+      schedule,
+      enabled: true,
+      force: options.force ?? false,
+      createdAt: now,
+      nextRunAt,
+      expiresAt,
+      runCount: 0,
+      history: [],
+    }
+
+    this.tasks.set(id, task)
+    this.persist()
+    return task
+  }
+
+  listTasks(): ScheduledTask[] {
+    return Array.from(this.tasks.values()).sort((a, b) => a.nextRunAt - b.nextRunAt)
+  }
+
+  getTask(id: string): ScheduledTask | undefined {
+    return this.tasks.get(id)
+  }
+
+  async toggleTask(id: string, enabled: boolean): Promise<boolean> {
+    const task = this.tasks.get(id)
+    if (!task) return false
+    task.enabled = enabled
+    // enable 时若 nextRunAt 已过期，重算，避免 enable 瞬间立即触发
+    if (enabled && task.nextRunAt < Date.now()) {
+      const schedule = task.schedule
+      if (schedule.mode === 'interval') {
+        task.nextRunAt = Date.now() + schedule.intervalMs
+      } else {
+        task.nextRunAt = (await computeNextCronRunAt(schedule.cronExpression, Date.now())) ?? Date.now()
+      }
+    }
+    this.persist()
+    return true
+  }
+
+  deleteTask(id: string): boolean {
+    const deleted = this.tasks.delete(id)
+    if (deleted) this.persist()
+    return deleted
+  }
+
+  async runTaskNow(id: string): Promise<boolean> {
+    const task = this.tasks.get(id)
+    if (!task) return false
+    const dispatched = await this.dispatchTask(task)
+    this.persist()
+    return dispatched
+  }
+
+  // ── 调度 ──
+
+  startScheduler(): void {
+    if (this.tickTimer) return
+    this.tickTimer = setInterval(() => void this.tickScheduler(), TICK_INTERVAL_MS)
+  }
+
+  stopScheduler(): void {
+    if (this.tickTimer) {
+      clearInterval(this.tickTimer)
+      this.tickTimer = null
+    }
+  }
+
+  async tickScheduler(): Promise<void> {
+    const now = Date.now()
+
+    // 1. 过期清理
+    for (const [id, task] of this.tasks) {
+      if (task.expiresAt && now >= task.expiresAt) {
+        this.tasks.delete(id)
+      }
+    }
+
+    // 2. 标记到期
+    for (const task of this.tasks.values()) {
+      if (task.enabled && now >= task.nextRunAt) {
+        task.pending = true
+      }
+    }
+
+    // 3. dispatch pending 任务（按 nextRunAt 排序）
+    const pending = [...this.tasks.values()]
+      .filter(t => t.pending)
+      .sort((a, b) => a.nextRunAt - b.nextRunAt)
+
+    for (const task of pending) {
+      if (task.pending) {
+        await this.dispatchTask(task)
+      }
+    }
+
+    this.persist()
+  }
+
+  // ── dispatch ──
+
+  /**
+   * dispatch 单个任务。返回 true 表示真的发送了 message，false 表示 no-op
+   * （task disabled / rate-limited / 非 force 且 busy）。
+   * sendMessage 抛错时记录 failed 状态但不 rethrow，让 tick 继续处理其他任务。
+   */
+  async dispatchTask(task: ScheduledTask): Promise<boolean> {
+    if (!task.enabled) return false
+
+    // 检查 force 或 idle
+    if (!task.force) {
+      if (!this.ctx.isIdle() || this.ctx.hasPendingMessages()) {
+        return false // 延迟到下次 tick
+      }
+    }
+
+    // 检查速率限制
+    if (!this.hasDispatchCapacity(Date.now())) return false
+
+    // 注入 message
+    try {
+      this.pi.sendMessage(
+        { content: task.prompt, customType: 'pi-scheduler:dispatched', display: true },
+        { deliverAs: 'followUp', triggerTurn: true },
+      )
+    } catch {
+      task.lastStatus = 'failed'
+      task.pending = false
+      task.history.push({ at: Date.now(), status: 'failed' })
+      if (task.history.length > 20) task.history.shift()
+      return false
+    }
+
+    // 更新状态
+    task.runCount++
+    task.lastRunAt = Date.now()
+    task.lastStatus = 'success'
+    task.pending = false
+    task.history.push({ at: Date.now(), status: 'success' })
+    if (task.history.length > 20) task.history.shift()
+
+    // 计算下次执行
+    if (task.kind === 'once') {
+      this.tasks.delete(task.id)
+    } else {
+      const schedule = task.schedule
+      if (schedule.mode === 'interval') {
+        task.nextRunAt = Date.now() + schedule.intervalMs
+      } else {
+        task.nextRunAt = (await computeNextCronRunAt(schedule.cronExpression, Date.now())) ?? Date.now()
+      }
+    }
+
+    this.dispatchTimestamps.push(Date.now())
+    return true
+  }
+
+  private hasDispatchCapacity(now: number): boolean {
+    const oneMinuteAgo = now - 60_000
+    this.dispatchTimestamps = this.dispatchTimestamps.filter(t => t > oneMinuteAgo)
+    return this.dispatchTimestamps.length < RATE_LIMIT_PER_MINUTE
+  }
+
+  // ── 持久化 ──
+
+  loadTasks(): void {
+    const store = this.store.load()
+    this.tasks = new Map(store.tasks.map(t => [t.id, t]))
+  }
+
+  persist(): void {
+    const store: SchedulerStore = { version: 1, tasks: Array.from(this.tasks.values()) }
+    this.store.persist(store)
+  }
+
+  persistSync(): void {
+    const store: SchedulerStore = { version: 1, tasks: Array.from(this.tasks.values()) }
+    this.store.persistSync(store)
+  }
+
+  // ── 工具方法 ──
+
+  getTaskCount(): number {
+    return this.tasks.size
+  }
+}

package/src/store.ts

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import type { ScheduledTask, SchedulerStore } from './types.js'
+
+const HISTORY_LIMIT = 20
+const DEBOUNCE_MS = 2000
+
+/**
+ * 获取 store 文件路径：~/.pi/agent/scheduler/<root>/<segments>/scheduler.json
+ * workspace 路径隔离，不同 cwd 存不同文件。
+ */
+export function getStorePath(cwd: string): string {
+  const home = os.homedir()
+  const resolved = path.resolve(cwd)
+  const parsed = path.parse(resolved)
+  const segments = resolved.slice(parsed.root.length)
+    .split(path.sep).filter(Boolean)
+  const root = parsed.root
+    .replaceAll(/[^a-zA-Z0-9]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .toLowerCase() || 'root'
+  return path.join(home, '.pi', 'agent', 'scheduler', root, ...segments, 'scheduler.json')
+}
+
+/**
+ * GC：裁剪 history > 20 条 + 移除过期任务
+ */
+function gc(store: SchedulerStore): SchedulerStore {
+  const now = Date.now()
+  const tasks = store.tasks
+    .filter(t => !t.expiresAt || t.expiresAt > now)
+    .map(t => ({
+      ...t,
+      history: t.history.slice(-HISTORY_LIMIT),
+    }))
+  return { ...store, tasks }
+}
+
+/**
+ * 创建 store 实例。
+ * load: 读取 JSON + 解析 + 降级
+ * persist: debounced 写入 + GC
+ * persistSync: 同步写入（session_shutdown 用）
+ */
+export function createStore(cwd: string) {
+  const storePath = getStorePath(cwd)
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+  function ensureDir(): void {
+    const dir = path.dirname(storePath)
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+  }
+
+  function load(): SchedulerStore {
+    try {
+      if (!fs.existsSync(storePath)) {
+        return { version: 1, tasks: [] }
+      }
+      const content = fs.readFileSync(storePath, 'utf-8')
+      const data = JSON.parse(content) as Partial<SchedulerStore>
+      // 版本迁移：缺失字段给默认值
+      return {
+        version: data.version ?? 1,
+        tasks: (data.tasks ?? []).map((t: Partial<ScheduledTask>) => ({
+          id: t.id ?? '',
+          name: t.name ?? '',
+          prompt: t.prompt ?? '',
+          kind: t.kind ?? 'recurring' as const,
+          schedule: t.schedule ?? { mode: 'interval' as const, intervalMs: 60000 },
+          createdAt: t.createdAt ?? 0,
+          nextRunAt: t.nextRunAt ?? 0,
+          runCount: t.runCount ?? 0,
+          enabled: t.enabled ?? true,
+          force: t.force ?? false,
+          history: t.history ?? [],
+          expiresAt: t.expiresAt,
+          lastRunAt: t.lastRunAt,
+          lastStatus: t.lastStatus,
+        })),
+      }
+    } catch {
+      // 文件损坏降级
+      console.warn(`[scheduler] Failed to load store from ${storePath}, using empty store`)
+      return { version: 1, tasks: [] }
+    }
+  }
+
+  function writeSync(store: SchedulerStore): void {
+    ensureDir()
+    const cleaned = gc(store)
+    fs.writeFileSync(storePath, JSON.stringify(cleaned, null, 2), 'utf-8')
+  }
+
+  function persist(store: SchedulerStore): void {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer)
+    }
+    debounceTimer = setTimeout(() => {
+      writeSync(store)
+      debounceTimer = null
+    }, DEBOUNCE_MS)
+  }
+
+  function persistSync(store: SchedulerStore): void {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer)
+      debounceTimer = null
+    }
+    writeSync(store)
+  }
+
+  return { load, persist, persistSync, storePath }
+}

package/src/tool.ts

@@ -0,0 +1,131 @@
+import { Static, Type } from '@sinclair/typebox'
+
+import { formatRelativeTime, formatSchedule } from './format.js'
+import { computeNextRuns, parseSchedule } from './parsing.js'
+import type { SchedulerRuntime } from './runtime.js'
+
+// TODO: add renderResult/renderCall to registerTool calls (standards.md §4.3)
+
+// ── schedule tool ──
+
+export const ScheduleParams = Type.Object({
+  prompt: Type.String({ description: 'Message to inject when the task fires.' }),
+  schedule: Type.String({ description: 'Schedule spec: duration (5m/2h/1d) for interval, or cron expression (*/10 * * * *).' }),
+  kind: Type.Optional(Type.Union([Type.Literal('once'), Type.Literal('recurring')], { description: 'Task kind. Default: recurring.' })),
+  name: Type.Optional(Type.String({ description: 'Human-readable task name. Auto-generated from prompt if omitted.' })),
+  expires: Type.Optional(Type.String({ description: 'Expiry duration (30m/2h/7d). Default: 7d. Pass "never" to disable.' })),
+  force: Type.Optional(Type.Boolean({ description: 'Dispatch even when agent is busy. Default: false.' })),
+})
+
+export type ScheduleParamsT = Static<typeof ScheduleParams>
+
+export const scheduleGuidelines = [
+  'This tool creates a scheduled task.',
+  'Schedule accepts duration (5m, 2h, 1d) for interval-based or cron expression for time-based.',
+  'Default kind is recurring. Set kind="once" for one-time reminders.',
+  'After creation, the response includes task id and next 5 run times.',
+  'Default expiry is 7 days. Use expires="never" for long-term tasks.',
+]
+
+export function createScheduleHandler(runtime: SchedulerRuntime) {
+  return async (params: ScheduleParamsT) => {
+    const { prompt, schedule: scheduleInput, kind, name, expires, force } = params
+
+    const parsed = await parseSchedule(scheduleInput)
+    if (!parsed) {
+      throw new Error(`Invalid schedule: "${scheduleInput}". Use duration (5m/2h/1d) or cron expression (*/10 * * * *).`)
+    }
+
+    const task = await runtime.addTask(prompt, parsed.spec, { kind, name, expires, force })
+
+    const nextRuns = await computeNextRuns(task.schedule, Date.now(), 5)
+    const summary = [
+      `Task "${task.name}" (${task.id}) created.`,
+      `Schedule: ${formatSchedule(task.schedule)}`,
+      `Kind: ${task.kind}`,
+      `Expires: ${task.expiresAt ? formatRelativeTime(task.expiresAt) : 'never'}`,
+      `Force: ${task.force ? 'yes' : 'no'}`,
+      '',
+      'Next 5 runs:',
+      ...nextRuns.map((t, i) => `  ${i + 1}. ${formatRelativeTime(t)}`),
+    ].join('\n')
+
+    return {
+      content: [{ type: 'text' as const, text: summary }],
+      details: { task, nextRuns },
+    }
+  }
+}
+
+// ── schedule_control tool ──
+
+export const ScheduleControlParams = Type.Object({
+  action: Type.Union([Type.Literal('list'), Type.Literal('toggle'), Type.Literal('delete'), Type.Literal('run')], { description: 'Action to perform.' }),
+  id: Type.Optional(Type.String({ description: 'Task id. Required for toggle/delete/run.' })),
+  enabled: Type.Optional(Type.Boolean({ description: 'Target enabled state. Required for toggle.' })),
+})
+
+export type ScheduleControlParamsT = Static<typeof ScheduleControlParams>
+
+export const controlGuidelines = [
+  'Use action="list" to see all scheduled tasks.',
+  'After listing, use the returned id for toggle/delete/run.',
+  'Prefer toggle(enabled=false) over delete for temporary pauses.',
+  'action="run" fires the task immediately.',
+]
+
+export function createScheduleControlHandler(runtime: SchedulerRuntime) {
+  return async (params: ScheduleControlParamsT) => {
+    const { action, id, enabled } = params
+
+    switch (action) {
+      case 'list': {
+        const tasks = runtime.listTasks()
+        if (tasks.length === 0) {
+          return { content: [{ type: 'text' as const, text: 'No scheduled tasks.' }], details: { tasks: [] } }
+        }
+        const lines = tasks.map(t =>
+          `${t.enabled ? '●' : '○'} ${t.id} ${t.name} · ${formatSchedule(t.schedule)} · ${formatRelativeTime(t.nextRunAt)}`
+        )
+        return {
+          content: [{ type: 'text' as const, text: lines.join('\n') }],
+          details: { tasks },
+        }
+      }
+
+      case 'toggle': {
+        if (!id) throw new Error('id is required for toggle.')
+        if (enabled === undefined) throw new Error('enabled is required for toggle.')
+        const success = await runtime.toggleTask(id, enabled)
+        if (!success) throw new Error(`Task ${id} not found.`)
+        return {
+          content: [{ type: 'text' as const, text: `Task ${id} ${enabled ? 'enabled' : 'disabled'}.` }],
+          details: { success },
+        }
+      }
+
+      case 'delete': {
+        if (!id) throw new Error('id is required for delete.')
+        const success = runtime.deleteTask(id)
+        if (!success) throw new Error(`Task ${id} not found.`)
+        return {
+          content: [{ type: 'text' as const, text: `Task ${id} deleted.` }],
+          details: { success },
+        }
+      }
+
+      case 'run': {
+        if (!id) throw new Error('id is required for run.')
+        const success = await runtime.runTaskNow(id)
+        if (!success) throw new Error(`Task ${id} not found.`)
+        return {
+          content: [{ type: 'text' as const, text: `Task ${id} executed.` }],
+          details: { success },
+        }
+      }
+
+      default:
+        throw new Error(`Unknown action: ${action}`)
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+// ── 调度规格 ──
+
+export type ScheduleMode = 'cron' | 'interval'
+
+export type ScheduleSpec =
+  | { mode: 'cron'; cronExpression: string }
+  | { mode: 'interval'; intervalMs: number }
+
+// ── 任务 ──
+
+export type TaskKind = 'once' | 'recurring'
+export type TaskStatus = 'pending' | 'running' | 'success' | 'failed'
+
+export interface ScheduledTask {
+  id: string                        // 8 位 hex，自动生成
+  name: string                      // 可读名称（用户指定或从 prompt 自动截取前 30 字）
+  prompt: string                    // 到期时注入的 message
+  kind: TaskKind
+  schedule: ScheduleSpec            // once 时 intervalMs = delayMs
+  enabled: boolean
+  force: boolean                    // true = 即使 agent busy 也 dispatch
+  createdAt: number
+  nextRunAt: number
+  expiresAt?: number                // undefined = 永不过期
+  runCount: number
+  lastRunAt?: number
+  lastStatus?: TaskStatus
+  history: ExecutionRecord[]        // 最近 20 条
+  pending?: boolean                 // 标记到期待 dispatch
+}
+
+export interface ExecutionRecord {
+  at: number
+  status: TaskStatus
+  snippet?: string                  // agent 回复前 100 字
+}
+
+// ── 持久化 ──
+
+export interface SchedulerStore {
+  version: 1
+  tasks: ScheduledTask[]
+}
+
+// ── 解析结果 ──
+
+export interface ParseScheduleResult {
+  spec: ScheduleSpec
+  note?: string
+}
+
+// ── 添加选项 ──
+
+export interface AddOptions {
+  name?: string
+  kind?: TaskKind
+  expires?: string
+  force?: boolean
+}

package/src/widget.ts

@@ -0,0 +1,34 @@
+import { formatRelativeTime, truncate } from './format.js'
+import type { ScheduledTask } from './types.js'
+
+/**
+ * 渲染 TUI status bar widget（string[]，配合 SDK setWidget 第一重载）。
+ * 格式：[scheduler] 3 scheduled · check-build in 4m · 1 overdue
+ *
+ * 不接受 theme 参数：string[] 重载本身不提供 theme，着色交给 Pi 默认渲染。
+ * overdue 用 [!] 纯文本标记（PR 已统一去 emoji）。
+ */
+export function renderSchedulerWidget(tasks: ScheduledTask[]): string[] {
+  if (tasks.length === 0) return []
+
+  const now = Date.now()
+  const enabled = tasks.filter(t => t.enabled)
+  const overdue = enabled.filter(t => t.nextRunAt <= now)
+  const upcoming = enabled
+    .filter(t => t.nextRunAt > now)
+    .sort((a, b) => a.nextRunAt - b.nextRunAt)
+
+  const parts: string[] = []
+  parts.push(`${enabled.length} scheduled`)
+
+  if (upcoming.length > 0) {
+    const next = upcoming[0]!
+    parts.push(`${truncate(next.name, 20)} ${formatRelativeTime(next.nextRunAt)}`)
+  }
+
+  if (overdue.length > 0) {
+    parts.push(`[!] ${overdue.length} overdue`)
+  }
+
+  return [`[scheduler] ${parts.join(' · ')}`]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['src/__tests__/**/*.test.ts'],
+  },
+})