@zhushanwen/pi-scheduler 0.0.2

package/src/__tests__/widget.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect,it } from 'vitest'
+
+import type { ScheduledTask } from '../types.js'
+import { renderSchedulerWidget } from '../widget.js'
+
+const makeTask = (overrides: Partial<ScheduledTask> = {}): ScheduledTask => ({
+  id: 'abc12345',
+  name: 'test task',
+  prompt: 'test prompt',
+  kind: 'recurring',
+  schedule: { mode: 'interval', intervalMs: 60000 },
+  enabled: true,
+  force: false,
+  createdAt: Date.now(),
+  nextRunAt: Date.now() + 60000,
+  runCount: 0,
+  history: [],
+  ...overrides,
+})
+
+describe('renderSchedulerWidget', () => {
+  it('returns empty array when no tasks', () => {
+    expect(renderSchedulerWidget([])).toEqual([])
+  })
+
+  it('renders task count', () => {
+    const tasks = [makeTask(), makeTask({ id: 'def67890', name: 'another' })]
+    const result = renderSchedulerWidget(tasks)
+    expect(result[0]).toContain('2 scheduled')
+  })
+
+  it('renders next upcoming task', () => {
+    const tasks = [makeTask({ name: 'check build' })]
+    const result = renderSchedulerWidget(tasks)
+    expect(result[0]).toContain('check build')
+    expect(result[0]).toContain('in')
+  })
+
+  it('renders overdue count', () => {
+    const tasks = [makeTask({ nextRunAt: Date.now() - 1000 })]
+    const result = renderSchedulerWidget(tasks)
+    expect(result[0]).toContain('1 overdue')
+  })
+
+  it('starts with [scheduler] prefix', () => {
+    const tasks = [makeTask()]
+    const result = renderSchedulerWidget(tasks)
+    expect(result[0]).toMatch(/^\[scheduler\]/)
+  })
+
+  // disabled 任务被过滤：scheduled 计数与 overdue/upcoming 都只统计 enabled
+  it('excludes disabled tasks from counts', () => {
+    const tasks = [
+      makeTask({ id: 'enabled1', name: 'active', enabled: true }),
+      makeTask({ id: 'disabled1', name: 'inactive', enabled: false, nextRunAt: Date.now() - 1000 }),
+    ]
+    const result = renderSchedulerWidget(tasks)
+    expect(result[0]).toContain('1 scheduled')
+    expect(result[0]).not.toContain('1 overdue')
+    expect(result[0]).toContain('active')
+    expect(result[0]).not.toContain('inactive')
+  })
+})

package/src/commands.ts

@@ -0,0 +1,150 @@
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
+
+import { formatRelativeTime, formatSchedule } from './format.js'
+import { parseSchedule } from './parsing.js'
+import type { SchedulerRuntime } from './runtime.js'
+
+/**
+ * Shell-style quote-aware tokenizer.
+ * Supports single/double quoted tokens (e.g. cron expressions with spaces).
+ * Quoted content is kept as a single token; quote chars are stripped from output.
+ */
+function tokenizeQuoted(input: string): string[] {
+  const tokens: string[] = []
+  let current = ''
+  let inQuote: '"' | "'" | null = null
+
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null
+      } else {
+        current += ch
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch
+    } else if (ch === ' ' || ch === '\t') {
+      if (current) {
+        tokens.push(current)
+        current = ''
+      }
+    } else {
+      current += ch
+    }
+  }
+  if (current) tokens.push(current)
+  return tokens
+}
+
+/**
+ * 注册 /schedule command。
+ * 消歧规则：第一个参数匹配子命令关键词则走对应分支，否则尝试 parseSchedule 创建任务。
+ *
+ * runtime 通过 getter 获取：registerScheduleCommand 在 factory 顶层调用，此时 session_start
+ * 尚未触发、runtime 还是 null。getArgumentCompletions / handler 真正执行时才读 runtime 当前值。
+ */
+export function registerScheduleCommand(
+  pi: ExtensionAPI,
+  getRuntime: () => SchedulerRuntime | null,
+) {
+  pi.registerCommand('schedule', {
+    description: 'Manage scheduled tasks. No args opens TUI. /schedule <schedule> <prompt> to create.',
+    getArgumentCompletions(prefix: string) {
+      const runtime = getRuntime()
+      const trimmed = prefix.trimStart()
+      const parts = trimmed.split(/\s+/).filter(Boolean)
+      if (parts.length <= 1) {
+        return [
+          { label: 'list', value: 'list', description: 'Show all scheduled tasks' },
+          { label: 'on', value: 'on ', description: 'Enable a task' },
+          { label: 'off', value: 'off ', description: 'Disable a task' },
+          { label: 'rm', value: 'rm ', description: 'Delete a task' },
+          { label: 'run', value: 'run ', description: 'Run a task now' },
+          { label: 'once', value: 'once ', description: 'Create a one-time reminder' },
+          { label: 'cron', value: "cron '", description: 'Create a cron-based task' },
+        ].filter(opt => opt.label.startsWith(trimmed.toLowerCase()))
+      }
+      // on/off/rm/run 后补全任务 id
+      if (['on', 'off', 'rm', 'run'].includes(parts[0]!) && runtime) {
+        return runtime.listTasks().map(t => ({
+          label: t.id,
+          value: t.id,
+          description: `${t.name} · ${formatSchedule(t.schedule)}`
+        }))
+      }
+      return null
+    },
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const result = await executeScheduleCommand(getRuntime(), args)
+      ctx.ui.notify(result, 'info')
+    },
+  })
+}
+
+/**
+ * Core logic for /schedule command. Extracted for testability (handler returns
+ * void per SDK contract; tests call this function directly to assert output).
+ */
+export async function executeScheduleCommand(
+  runtime: SchedulerRuntime | null,
+  args: string,
+): Promise<string> {
+  if (!runtime) return 'Scheduler not initialized: session not started.'
+
+  const trimmed = args.trim()
+  if (!trimmed) {
+    // TODO: 打开 TUI 管理器（W5 实现）
+    return 'TUI manager not yet implemented. Use /schedule list to see tasks.'
+  }
+
+  const parts = tokenizeQuoted(trimmed)
+  const first = parts[0]!.toLowerCase()
+
+  // 子命令路由
+  if (first === 'list') {
+    const tasks = runtime.listTasks()
+    if (tasks.length === 0) return 'No scheduled tasks.'
+    return tasks.map(t =>
+      `${t.enabled ? '●' : '○'} ${t.id} ${t.name} · ${formatSchedule(t.schedule)} · ${formatRelativeTime(t.nextRunAt)}`
+    ).join('\n')
+  }
+
+  if (first === 'on' || first === 'off') {
+    const id = parts[1]
+    if (!id) return `Usage: /schedule ${first} <id>`
+    const success = await runtime.toggleTask(id, first === 'on')
+    return success ? `Task ${id} ${first === 'on' ? 'enabled' : 'disabled'}.` : `Task ${id} not found.`
+  }
+
+  if (first === 'rm') {
+    const id = parts[1]
+    if (!id) return 'Usage: /schedule rm <id>'
+    const success = runtime.deleteTask(id)
+    return success ? `Task ${id} deleted.` : `Task ${id} not found.`
+  }
+
+  if (first === 'run') {
+    const id = parts[1]
+    if (!id) return 'Usage: /schedule run <id>'
+    const success = await runtime.runTaskNow(id)
+    return success ? `Task ${id} executed.` : `Task ${id} not found.`
+  }
+
+  // 创建任务分支
+  const kind = first === 'once' ? 'once' as const : first === 'cron' ? 'recurring' as const : undefined
+  const scheduleStart = kind ? 1 : 0
+  const scheduleInput = parts[scheduleStart]
+  if (!scheduleInput) return 'Usage: /schedule <schedule> <prompt>'
+
+  const prompt = parts.slice(scheduleStart + 1).join(' ')
+  if (!prompt) return 'Usage: /schedule <schedule> <prompt>'
+
+  const parsed = await parseSchedule(scheduleInput)
+  if (!parsed) {
+    return `Invalid schedule: "${scheduleInput}". Use duration (5m/2h/1d) or cron expression.`
+  }
+
+  const task = await runtime.addTask(prompt, parsed.spec, { kind })
+  return `Task "${task.name}" (${task.id}) created. Schedule: ${formatSchedule(task.schedule)}`
+}

package/src/format.ts

@@ -0,0 +1,77 @@
+import { formatDuration } from './parsing.js'
+import type { ScheduleSpec } from './types.js'
+
+/** Format ScheduleSpec to readable string */
+export function formatSchedule(spec: ScheduleSpec): string {
+  if (spec.mode === 'interval') {
+    return `every ${formatDuration(spec.intervalMs)}`
+  }
+  return spec.cronExpression
+}
+
+/**
+ * 格式化时间戳为相对时间字符串。
+ * 未来: "in 5m"
+ * 过去: "5m ago"
+ * 当前(+-5s): "now"
+ *
+ * now 可选参数：基准时间戳，默认 Date.now()。测试可传固定值快进/锁定，
+ * 生产调用方无需传（参数可选，行为不变）。
+ */
+export function formatRelativeTime(timestamp: number, now?: number): string {
+  const currentTime = now ?? Date.now()
+  const diff = timestamp - currentTime
+
+  // 5秒内视为"现在"
+  if (Math.abs(diff) < 5000) return 'now'
+
+  const absDiff = Math.abs(diff)
+  const units: [string, number][] = [
+    ['d', 86_400_000],
+    ['h', 3_600_000],
+    ['m', 60_000],
+    ['s', 1000],
+  ]
+
+  let formatted = ''
+  for (const [suffix, divisor] of units) {
+    if (absDiff >= divisor) {
+      const value = Math.floor(absDiff / divisor)
+      formatted = `${value}${suffix}`
+      break
+    }
+  }
+
+  if (!formatted) {
+    formatted = `${Math.round(absDiff / 1000)}s`
+  }
+
+  return diff > 0 ? `in ${formatted}` : `${formatted} ago`
+}
+
+/**
+ * 截断文本到指定长度，超出部分用 "..." 替代。
+ */
+export function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text
+  if (maxLen <= 3) return text.slice(0, maxLen)
+  return text.slice(0, maxLen - 3) + '...'
+}
+
+/**
+ * 生成任务 ID：8 位 hex。
+ */
+export function generateTaskId(): string {
+  const bytes = new Uint8Array(4)
+  crypto.getRandomValues(bytes)
+  return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * 从 prompt 自动生成任务名称：取前 30 字。
+ */
+export function autoName(prompt: string): string {
+  const trimmed = prompt.trim()
+  if (trimmed.length <= 30) return trimmed
+  return trimmed.slice(0, 27) + '...'
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+
+import { registerScheduleCommand } from './commands.js'
+import { SchedulerRuntime } from './runtime.js'
+import {
+  controlGuidelines,
+  createScheduleControlHandler,
+  createScheduleHandler,
+  ScheduleControlParams,
+  type ScheduleControlParamsT,
+  scheduleGuidelines,
+  ScheduleParams,
+  type ScheduleParamsT,
+} from './tool.js'
+import { renderSchedulerWidget } from './widget.js'
+
+/** widget 刷新节奏：对齐 runtime 的 TICK_INTERVAL_MS（30s），保证 nextRunAt 倒计时随 tick 更新。 */
+const WIDGET_REFRESH_MS = 30_000
+
+/**
+ * pi-scheduler extension factory。
+ * 注册 schedule + schedule_control 两个 tool、/schedule command、session 事件。
+ *
+ * runtime 生命周期：在 session_start 中创建（依赖 ctx），factory 顶层只声明为 null。
+ * tool/command 的 execute/handler 通过 getRuntime() 延迟读取，避免在 factory 顶层
+ * 捕获 null——那时 session_start 尚未触发，runtime! 非空断言会骗过编译器但运行时是 null。
+ */
+export default function schedulerExtension(pi: ExtensionAPI): void {
+  let runtime: SchedulerRuntime | null = null
+  // widget 刷新计时器：与 runtime 同生命周期，session_shutdown 时清理。
+  let widgetTimer: ReturnType<typeof setInterval> | null = null
+
+  const getRuntime = (): SchedulerRuntime => {
+    if (!runtime) throw new Error('Scheduler not initialized: session not started')
+    return runtime
+  }
+
+  pi.on('session_start', (_event, ctx: ExtensionContext) => {
+    runtime = new SchedulerRuntime(ctx.cwd, pi, ctx)
+    runtime.loadTasks()
+    runtime.startScheduler()
+
+    // 注册 widget（SDK setWidget 第一重载：直接传 string[]）。
+    // string[] 只渲染一次，调度器需要随 task 状态/nextRunAt 倒计时刷新，
+    // 因此用一个对齐 TICK_INTERVAL_MS 的 interval 周期性重发 string[]，
+    // 等价于 plan 扩展的 push 模式（plan/src/widget.ts:13）。
+    refreshWidget(ctx)
+    widgetTimer = setInterval(() => refreshWidget(ctx), WIDGET_REFRESH_MS)
+  })
+
+  pi.on('session_shutdown', () => {
+    if (widgetTimer) {
+      clearInterval(widgetTimer)
+      widgetTimer = null
+    }
+    if (runtime) {
+      runtime.persistSync()
+      runtime.stopScheduler()
+    }
+  })
+
+  // 注册 schedule tool
+  // execute 内联闭包：从 SDK 全签名 (toolCallId, params, signal, onUpdate, ctx) 提取 params 转调
+  // handler，并 catch 业务层抛出的错误转为 { isError: true }（standards.md §4.2 禁止抛）。
+  pi.registerTool({
+    name: 'schedule',
+    label: 'Schedule',
+    description: 'Create a scheduled task that fires a message at intervals or cron schedule.',
+    parameters: ScheduleParams,
+    promptGuidelines: scheduleGuidelines,
+    async execute(
+      _toolCallId: string,
+      params: ScheduleParamsT,
+      _signal: AbortSignal | undefined,
+      _onUpdate,
+      _ctx: ExtensionContext,
+    ) {
+      try {
+        return await createScheduleHandler(getRuntime())(params)
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: {},
+          isError: true,
+        }
+      }
+    },
+  })
+
+  // 注册 schedule_control tool
+  pi.registerTool({
+    name: 'schedule_control',
+    label: 'Schedule Control',
+    description: 'Manage scheduled tasks: list, toggle, delete, or run immediately.',
+    parameters: ScheduleControlParams,
+    promptGuidelines: controlGuidelines,
+    async execute(
+      _toolCallId: string,
+      params: ScheduleControlParamsT,
+      _signal: AbortSignal | undefined,
+      _onUpdate,
+      _ctx: ExtensionContext,
+    ) {
+      try {
+        return await createScheduleControlHandler(getRuntime())(params)
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: {},
+          isError: true,
+        }
+      }
+    },
+  })
+
+  // 注册 /schedule command。传 getter 而非 runtime 实例：factory 执行时 runtime 还是 null。
+  registerScheduleCommand(pi, () => runtime)
+
+  /**
+   * 重新计算并推送 scheduler widget（string[] 重载）。
+   * 读外层 runtime 变量而非 getRuntime()：session_start 尚未触发时刷新不应报错，直接跳过。
+   */
+  function refreshWidget(ctx: ExtensionContext): void {
+    if (!runtime) return
+    ctx.ui.setWidget('scheduler', renderSchedulerWidget(runtime.listTasks()))
+  }
+}

package/src/parsing.ts

@@ -0,0 +1,208 @@
+import type { ParseScheduleResult, ScheduleSpec } from './types.js'
+
+// ── Duration 解析 ──
+
+const DURATION_RE = /^(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hr|hours?|d|days?)$/i
+
+const DURATION_MULTIPLIERS: Record<string, number> = {
+  s: 1000, sec: 1000, second: 1000, seconds: 1000,
+  m: 60_000, min: 60_000, minute: 60_000, minutes: 60_000,
+  h: 3_600_000, hr: 3_600_000, hour: 3_600_000, hours: 3_600_000,
+  d: 86_400_000, day: 86_400_000, days: 86_400_000,
+}
+
+/**
+ * 解析 duration 字符串为毫秒数。
+ * 支持：5s, 5m, 2h, 1d, 30seconds, 2hours 等
+ * 返回 undefined 表示无法解析。
+ */
+export function parseDuration(text: string): number | undefined {
+  const match = DURATION_RE.exec(text.trim())
+  if (!match) return undefined
+  const value = parseInt(match[1]!, 10)
+  const unit = match[2]!.toLowerCase()
+  const multiplier = DURATION_MULTIPLIERS[unit]
+  if (multiplier === undefined) return undefined
+  return value * multiplier
+}
+
+/**
+ * 格式化毫秒数为可读 duration 字符串。
+ * 优先使用最大单位：300000 → "5m"，不是 "300s"
+ */
+export function formatDuration(ms: number): string {
+  if (ms <= 0) return '0s'
+
+  const units: [string, number][] = [
+    ['d', 86_400_000],
+    ['h', 3_600_000],
+    ['m', 60_000],
+    ['s', 1000],
+  ]
+
+  for (const [suffix, divisor] of units) {
+    if (ms >= divisor && ms % divisor === 0) {
+      return `${ms / divisor}${suffix}`
+    }
+  }
+
+  // 兜底：用秒表示
+  return `${Math.round(ms / 1000)}s`
+}
+
+// ── Cron 解析 ──
+
+let cronerModule: typeof import('croner') | null | undefined
+
+async function getCroner(): Promise<typeof import('croner') | null> {
+  if (cronerModule !== undefined) return cronerModule
+  try {
+    cronerModule = await import('croner')
+    return cronerModule
+  } catch {
+    cronerModule = null
+    return null
+  }
+}
+
+/**
+ * 规范化 cron 表达式：5 字段自动补秒字段。
+ * 返回 undefined 表示无效。
+ */
+export function normalizeCronExpression(input: string): { expression: string; note?: string } | undefined {
+  const trimmed = input.trim()
+  if (!trimmed) return undefined
+
+  const parts = trimmed.split(/\s+/)
+
+  // 6 字段原样返回
+  if (parts.length === 6) {
+    return { expression: trimmed }
+  }
+
+  // 5 字段补秒字段
+  if (parts.length === 5) {
+    return {
+      expression: `0 ${trimmed}`,
+      note: 'Auto-prepended seconds field (0)',
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * 计算 cron 表达式的下次执行时间。
+ * 返回 undefined 表示表达式无效或 croner 不可用。
+ */
+export async function computeNextCronRunAt(
+  expression: string,
+  from?: number,
+): Promise<number | undefined> {
+  const croner = await getCroner()
+  if (!croner) return undefined
+
+  try {
+    const normalized = normalizeCronExpression(expression)
+    if (!normalized) return undefined
+
+    const job = new croner.Cron(normalized.expression, { startAt: from ? new Date(from) : undefined })
+    const next = job.nextRun()
+    return next ? next.getTime() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 计算 cron 表达式的多个未来执行时间。
+ * count 默认 5。
+ */
+export async function computeNextCronRuns(
+  expression: string,
+  from?: number,
+  count = 5,
+): Promise<number[]> {
+  const croner = await getCroner()
+  if (!croner) return []
+
+  try {
+    const normalized = normalizeCronExpression(expression)
+    if (!normalized) return []
+
+    const job = new croner.Cron(normalized.expression, { startAt: from ? new Date(from) : undefined })
+    const runs: number[] = []
+    let current = from ? new Date(from) : new Date()
+
+    for (let i = 0; i < count; i++) {
+      const next = job.nextRun(current)
+      if (!next) break
+      runs.push(next.getTime())
+      current = next
+    }
+
+    return runs
+  } catch {
+    return []
+  }
+}
+
+// ── 统一解析 ──
+
+/**
+ * 统一解析 schedule 输入。
+ * 不含空格 → duration 解析 → interval mode
+ * 含空格 → cron 解析 → cron mode
+ * 都失败 → undefined
+ */
+export async function parseSchedule(
+  input: string,
+): Promise<ParseScheduleResult | undefined> {
+  const trimmed = input.trim()
+  if (!trimmed) return undefined
+
+  // 不含空格 → 尝试 duration
+  if (!trimmed.includes(' ')) {
+    const ms = parseDuration(trimmed)
+    if (ms !== undefined) {
+      return {
+        spec: { mode: 'interval', intervalMs: ms },
+      }
+    }
+    return undefined
+  }
+
+  // 含空格 → 尝试 cron
+  const normalized = normalizeCronExpression(trimmed)
+  if (normalized) {
+    // 验证 cron 表达式有效
+    const nextRun = await computeNextCronRunAt(trimmed)
+    if (nextRun !== undefined) {
+      return {
+        spec: { mode: 'cron', cronExpression: normalized.expression },
+        note: normalized.note,
+      }
+    }
+  }
+
+  return undefined
+}
+
+// ── Next Runs 计算 ──
+
+/**
+ * 统一计算多个未来执行时间。
+ * interval 模式直接乘法，cron 模式调用 croner。
+ */
+export async function computeNextRuns(
+  spec: ScheduleSpec,
+  from?: number,
+  count = 5,
+): Promise<number[]> {
+  if (spec.mode === 'interval') {
+    const start = from ?? Date.now()
+    return Array.from({ length: count }, (_, i) => start + spec.intervalMs * (i + 1))
+  }
+
+  return computeNextCronRuns(spec.cronExpression, from, count)
+}