@zhushanwen/pi-scheduler 0.5.2 → 0.8.0

package/README.md

@@ -228,7 +228,7 @@ npx vitest run src/__tests__/<file>.test.ts   # 单个文件
 
 测试策略：
 
-- **依赖反转**：`SchedulerRuntime` 只依赖 `SchedulerBackend` 接口（`sendMessage` / `appendEntry` / `now`），不触碰 FS/pi。测试注入 `MockSchedulerBackend`（`src/backend.ts` 同文件 export）实现零副作用测试
+- **依赖反转**：`SchedulerRuntime` 只依赖 `SchedulerBackend` 接口（`sendMessage` / `appendEntry` / `now`），不触碰 FS/pi。测试注入 `MockSchedulerBackend`（`src/__tests__/mock-backend.ts`，ext-simplify-08 L9 自 `src/backend.ts` 迁出的测试专用实现）实现零副作用测试
 - **纯函数**：`parseDuration` / `formatDuration` / `parseSchedule` / `computeNextRunAt` / `computeNextRuns`（`src/parsing.ts`）无副作用，可直接断言
 - **重放折叠**：custom entry 折叠协议（upsert / advance / toggle / delete，含 nextRunAt 重放恢复、fork owner 过滤）
 - **旧 store 导入**：rename `.imported` 原子收敛（单成功者、崩溃恢复）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.5.2",
+  "version": "0.8.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -30,7 +30,6 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",
-    "croner": "^9.0.0",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
@@ -39,14 +38,11 @@
     },
     "typebox": {
       "optional": true
-    },
-    "croner": {
-      "optional": true
     }
   },
   "dependencies": {
-    "@xyz-agent/session-delivery": "0.3.1",
-    "@zhushanwen/pi-ext-guards": "0.3.0",
+    "croner": "^9.0.0",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
     "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "scripts": {

package/skills/scheduler-ext-config/SKILL.md

@@ -59,7 +59,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 - **5 字段**（分 时 日 月 周）：自动在最前面补秒字段 `0`，变成 6 字段。例 `*/10 * * * *` → `0 */10 * * * *`（每 10 分钟）。
 - **6 字段**（秒 分 时 日 月 周）：原样使用。
 - 其他字段数（<5 或 >6）视为无效。
-- 底层用 `croner` 库（peerDependency，运行时动态 `import('croner')`；未安装时 cron 任务全部解析失败，interval 不受影响）。
+- 底层用 `croner` 库（dependencies + 静态 import，解析器随包安装恒在盘；cron 解析失败即表达式无效，interval 不受影响）。
 - 创建时即校验表达式有效性（算不出下次执行时间 → `INVALID_SCHEDULE`）；运行中表达式失效（极少见，如月份边界）→ 任务被停用并记 `lastError='cron expression invalid'`。
 
 示例：`*/30 * * * *`（每 30 分）、`0 9 * * 1-5`（工作日早 9 点）、`0 0 * * *`（每天 0 点）。
@@ -185,7 +185,7 @@ schedule({ prompt: "...", schedule: "1h", kind: "recurring", force: true, expire
 
 ## 备注
 
-- **croner 依赖**：cron 模式依赖 `croner`（peerDependency）。未安装时所有 cron 任务解析失败（返回 `INVALID_SCHEDULE`），interval 任务不受影响。集成方（如 xyz-agent mandatory 安装）需确保 `croner` 可用。
+- **croner 依赖**：cron 模式依赖 `croner`（dependencies，随包自动安装 + 静态 import，2026-09 0.6.0 起；此前为 optional peer，独立安装形态下 cron 任务会静默失败）。cron 解析失败（`INVALID_SCHEDULE`）= 表达式无效，不存在「解析器未安装」形态。
 - **数据目录隔离**：任务存储在 `getAgentDir()` 指向的 session JSONL。xyz-agent 通过 `XYZ_AGENT_DATA_DIR` / `PI_CODING_AGENT_DIR` 隔离实例时，任务随 session 落在隔离目录，与 `~/.pi/agent` 互不干扰。
 - **无配置 schema 可编辑**：scheduler 的所有状态都由运行时命令产生，没有可手动编辑的配置文件。要「批量预置任务」只能在 session 内逐条创建（或迁移旧 store）。
 - **TUI 管理器未实现**：无参 `/schedule` 当前只返回提示，任务管理请用 `list`/`on`/`off`/`rm`/`run` 子命令或 `schedule_control` 工具。

package/src/__tests__/U4-DISPATCH_INFLIGHT.test.ts

@@ -5,13 +5,13 @@
  * (1) 同一 taskId 的 dispatchTask 并发调用 → 第二次立即返回 false + logger.warn
  * (2) 第一次 dispatchTask 完成后（finally 清除）→ 第二次正常执行
  *
- * 断言 delivery send 调用总次数为 1（拦截场景）或 2（串行场景）。
+ * 断言 backend.sendMessage 调用总次数为 1（拦截场景）或 2（串行场景）。
  */
 import { describe, expect, it, vi } from 'vitest'
 
 import { getLogger } from '@zhushanwen/pi-extension-logger'
 
-import { MockSchedulerBackend } from '../backend.js'
+import { MockSchedulerBackend } from './mock-backend.js'
 import { SchedulerRuntime } from '../runtime.js'
 
 describe('U4_DISPATCH_INFLIGHT: 调用方 in-flight 守卫', () => {
@@ -25,13 +25,9 @@ describe('U4_DISPATCH_INFLIGHT: 调用方 in-flight 守卫', () => {
     })
     const backend = new MockSchedulerBackend()
     backend.sendMessage = vi.fn(() => sendPromise)
-    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+    const runtime = new SchedulerRuntime(backend)
 
-    const task = await runtime.addTask(
-      'inflight-test',
-      { mode: 'interval', intervalMs: 60_000 },
-      { force: true },
-    )
+    const task = await runtime.addTask('inflight-test', { mode: 'interval', intervalMs: 60_000 })
 
     // 第一次 dispatch（挂起）
     const first = runtime.dispatchTask(task)
@@ -58,13 +54,9 @@ describe('U4_DISPATCH_INFLIGHT: 调用方 in-flight 守卫', () => {
 
   it('(2) 第一次完成后 → 第二次 dispatchTask 正常执行（send 调 2 次）', async () => {
     const backend = new MockSchedulerBackend()
-    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+    const runtime = new SchedulerRuntime(backend)
 
-    const task = await runtime.addTask(
-      'serial-inflight',
-      { mode: 'interval', intervalMs: 60_000 },
-      { force: true },
-    )
+    const task = await runtime.addTask('serial-inflight', { mode: 'interval', intervalMs: 60_000 })
 
     // 第一次 dispatch（串行等待完成）
     const first = await runtime.dispatchTask(task)
@@ -80,30 +72,4 @@ describe('U4_DISPATCH_INFLIGHT: 调用方 in-flight 守卫', () => {
     // send 被调 2 次（串行完成）
     expect(backend.sentMessages).toHaveLength(2)
   })
-
-  it('(3) 非 force + 有 delivery handle 时，in-flight 守卫同样拦截并发 dispatch', async () => {
-    const warnSpy = vi.spyOn(getLogger('scheduler'), 'warn').mockImplementation(() => {})
-    const backend = new MockSchedulerBackend()
-    backend.deliveryHandle = {
-      send: vi.fn(),
-      sendChecked: vi.fn(),
-      flush: vi.fn(),
-      depth: vi.fn(() => 0),
-      dispose: vi.fn(),
-    } as any
-    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
-
-    const task = await runtime.addTask('delivery-inflight', { mode: 'interval', intervalMs: 60_000 })
-
-    const first = runtime.dispatchTask(task)
-    const second = await runtime.dispatchTask(task)
-
-    expect(await first).toBe(true)
-    expect(second).toBe(false)
-    expect(backend.deliveryHandle.send).toHaveBeenCalledTimes(1)
-
-    const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
-    expect(warnText).toContain('already in flight')
-    warnSpy.mockRestore()
-  })
 })

package/src/__tests__/backend.test.ts

@@ -1,11 +1,9 @@
 import { describe, expect, it } from 'vitest'
 
-import { MockSchedulerBackend } from '../backend.js'
+import { MockSchedulerBackend } from './mock-backend.js'
 import { SchedulerRuntime } from '../runtime.js'
 import type { SchedulerEntryOp, TaskSnapshot } from '../types.js'
 
-const mockCtx = { isIdle: () => true, hasPendingMessages: () => false }
-
 /** 构造 base task 快照（upsert op 用）。 */
 function snapshot(overrides: Partial<TaskSnapshot> = {}): TaskSnapshot {
   return {
@@ -15,8 +13,7 @@ function snapshot(overrides: Partial<TaskSnapshot> = {}): TaskSnapshot {
     kind: 'recurring',
     schedule: { mode: 'interval', intervalMs: 60000 },
     enabled: true,
-    force: false,
-    createdAt: 0,
+      createdAt: 0,
     nextRunAt: 100,
     runCount: 0,
     history: [],
@@ -103,7 +100,7 @@ describe('MockSchedulerBackend', () => {
   it('TC2: SchedulerRuntime with MockSchedulerBackend constructs and dispatches via mock', async () => {
     const backend = new MockSchedulerBackend()
     // 构造不抛错（无需 cwd/pi/store mock）
-    const runtime = new SchedulerRuntime(backend, mockCtx)
+    const runtime = new SchedulerRuntime(backend)
     const task = await runtime.addTask('probe', { mode: 'interval', intervalMs: 60000 })
     expect(task).toBeDefined()
     // addTask 后 append upsert op（append-only，零 FS）

package/src/__tests__/commands.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { MockSchedulerBackend } from '../backend.js'
+import { MockSchedulerBackend } from './mock-backend.js'
 import { executeScheduleCommand, registerScheduleCommand } from '../commands.js'
 import { SchedulerRuntime } from '../runtime.js'
 import { SchedulerService } from '../service.js'
@@ -27,7 +27,7 @@ describe('/schedule command', () => {
     }
     const backend = new MockSchedulerBackend()
     service = new SchedulerService(
-      new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false }),
+      new SchedulerRuntime(backend),
       () => backend.now(),
     )
     registerScheduleCommand(mockPi as never, () => service)
@@ -104,6 +104,7 @@ describe('/schedule command', () => {
   // ── 子命令路由：run ──
 
   it('run executes task', async () => {
+    // run 子命令的 dispatch 行为锚定 steer 直投路径
     const created = await service.create('test', '5m')
     const result = await executeScheduleCommand(service, `run ${created.data!.task.id}`)
     expect(result).toContain('executed')

package/src/__tests__/cron.test.ts

@@ -5,8 +5,8 @@
 // 此文件集中测 cron 相关导出：normalizeCronExpression / computeNextCronRunAt /
 // computeNextCronRuns / parseSchedule(cron) / computeNextRuns(cron)。
 //
-// croner 包是动态 import 的，测试时已安装（package.json peerDep croner ^9.0.0），
-// getCroner() 能正常返回模块，故 cron 路径在此可真实执行。
+// croner 是 dependencies + 静态 import（ext-simplify-08 D2），解析链同步化，
+// cron 路径在此真实执行（无需 mock）。
 
 import { describe, expect, it } from 'vitest'
 
@@ -60,16 +60,14 @@ describe('computeNextCronRuns', () => {
 describe('parseSchedule (cron 分支)', () => {
   it('5 字段 cron 表达式补秒字段', async () => {
     const result = await parseSchedule('*/10 * * * *')
-    expect(result).toEqual({
-      spec: { mode: 'cron', cronExpression: '0 */10 * * * *' },
-    })
+    expect(result).toEqual({ mode: 'cron', cronExpression: '0 */10 * * * *' })
   })
 
   it('工作日 9 点 cron 表达式返回 cron mode', async () => {
     const result = await parseSchedule('0 9 * * 1-5')
     expect(result).toBeDefined()
-    expect(result!.spec.mode).toBe('cron')
-    expect(result!.spec).toEqual({ mode: 'cron', cronExpression: '0 0 9 * * 1-5' })
+    expect(result!.mode).toBe('cron')
+    expect(result!).toEqual({ mode: 'cron', cronExpression: '0 0 9 * * 1-5' })
   })
 
   it('含空格但非法的表达式返回 undefined', async () => {

package/src/__tests__/importer.test.ts

@@ -40,7 +40,6 @@ function makeTask(overrides: Partial<ScheduledTask> = {}): ScheduledTask {
     kind: 'recurring',
     schedule: { mode: 'interval', intervalMs: 60000 },
     enabled: true,
-    force: false,
     createdAt: 1000,
     nextRunAt: 2000,
     runCount: 0,

package/src/__tests__/index-generation.test.ts

@@ -13,9 +13,11 @@
 //   isCtxStale 翻转为 true 且其泄漏 timer 在下个 tick 前置检查自停。闭包级实现（R3-M1
 //   修复前）在此拓扑下恒 false——正是被 R3 实测证伪的生产失效路径。
 //
-// 本文件用 InstrumentedRuntime（继承真实 SchedulerRuntime，仅记录构造第三参 isCtxStale）
-// 捕获注入回调。InstrumentedRuntime 全部行为继承父类，不影响装配链本身（F1 停旧 timer
-// 等行为由 index-session-start.test.ts U4 锚定，此处不重复）。
+// 本文件用 InstrumentedRuntime（继承真实 SchedulerRuntime，记录构造参 isCtxStale）
+// 捕获注入回调与装配事实。InstrumentedRuntime 全部行为继承父类，不影响装配链本身
+// （F1 停旧 timer 等行为由 index-session-start.test.ts U4 锚定，此处不重复）。
+// steer 直投模型（scheduler-steer-direct-dispatch）：装配点不再创建 delivery handle，
+// runtime 构造仅收 backend + isCtxStale 两参。
 
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -40,17 +42,16 @@ const { isCtxStaleCaptures, runtimeInstances } = vi.hoisted(() => ({
 }))
 
 // InstrumentedRuntime 继承真实实现（loadTasks/onAfterTick/startScheduler 均真实执行），
-// 仅捕获构造第三参并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）。
+// 仅捕获构造参（isCtxStale）并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）。
 vi.mock('../runtime.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../runtime.js')>()
   const RealSchedulerRuntime = actual.SchedulerRuntime
   class InstrumentedRuntime extends RealSchedulerRuntime {
     constructor(
       backend: ConstructorParameters<typeof RealSchedulerRuntime>[0],
-      ctx: ConstructorParameters<typeof RealSchedulerRuntime>[1],
       isCtxStale?: () => boolean,
     ) {
-      super(backend, ctx, isCtxStale)
+      super(backend, isCtxStale)
       isCtxStaleCaptures.push(isCtxStale)
       runtimeInstances.push(this)
     }

package/src/__tests__/index-session-start.test.ts

@@ -45,8 +45,8 @@ function createMockPi(): {
 
 /**
  * 最小 fake ctx：覆盖 session_start 装配链读到的全部字段——PiSchedulerBackend 构造
- * （sessionManager）、SchedulerRuntime 构造（isIdle/hasPendingMessages）、importLegacyStore
- * （cwd，已 mock）、refreshWidget（ui.setWidget）。
+ * （sessionManager）、runtime 装配（构造器直传——
+ * L2/L3）、importLegacyStore（cwd，已 mock）、refreshWidget（ui.setWidget）。
  * setWidget 以独立引用导出：session_start 初始渲染 + 每次 tick 末 onAfterTick 各调一次，
  * 是「哪个 runtime 的 timer 还在 tick」的行为观测面。
  */

package/src/__tests__/mock-backend.ts

@@ -0,0 +1,58 @@
+import type { SchedulerBackend } from '../backend.js'
+import { replayFoldEntries, type SchedulerEntryLike } from '../replay.js'
+import type { ScheduledTask, SchedulerEntryOp } from '../types.js'
+
+// 测试专用 mock（ext-simplify-08 L9：从 backend.ts 迁出——导出面即测试面的收敛，
+// 生产模块不再携带测试脚手架；MockSchedulerBackend/SentMessage 零生产引用）。
+
+export interface SentMessage {
+  msg: { content: string; customType: string; display: boolean }
+  opts?: { deliverAs?: 'steer'; triggerTurn?: boolean }
+}
+
+/**
+ * Mock 后端：零 session/FS 副作用，记录 sendMessage/appendEntry 调用，支持注入固定时间与 fake entries。
+ *
+ * 能力：
+ * - sentMessages: 每次 sendMessage 的 {msg, opts} 记录
+ * - appendedOps: 每次 appendEntry 收到的 SchedulerEntryOp（测 runtime 各 op 断言）
+ * - fakeEntries / fakeSessionFile: loadTasks 经 replayFoldEntries 的注入源（测 backend→replay 委托）
+ * - nowValue: now() 返回固定值，缺省 Date.now()
+ * - appendError: 注入后 appendEntry 抛该错（测 ER-APPEND-FAIL 捕获路径）
+ */
+export class MockSchedulerBackend implements SchedulerBackend {
+  sentMessages: SentMessage[] = []
+  appendedOps: SchedulerEntryOp[] = []
+  fakeEntries: SchedulerEntryLike[] = []
+  fakeSessionFile: string | undefined = '/test/session.json'
+  nowValue: number | undefined
+  appendError: Error | null = null
+
+  async sendMessage(
+    msg: { content: string; customType: string; display: boolean },
+    opts?: { deliverAs?: 'steer'; triggerTurn?: boolean },
+  ): Promise<void> {
+    this.sentMessages.push({ msg, opts })
+  }
+
+  appendEntry(op: SchedulerEntryOp): void {
+    if (this.appendError) throw this.appendError
+    this.appendedOps.push(op)
+  }
+
+  getSessionFile(): string | undefined {
+    return this.fakeSessionFile
+  }
+
+  now(): number {
+    return this.nowValue ?? Date.now()
+  }
+
+  /**
+   * 读路径（非接口成员，与 PiSchedulerBackend.loadTasks 对称）：经 replayFoldEntries 折叠
+   * fakeEntries + fakeSessionFile 恢复任务。测试用它验证 backend→replay 委托（TC-W-BACKEND-REPLAY）。
+   */
+  loadTasks(): ScheduledTask[] {
+    return [...replayFoldEntries(this.fakeEntries, this.fakeSessionFile).values()]
+  }
+}

package/src/__tests__/parsing.test.ts

@@ -100,9 +100,7 @@ describe('normalizeCronExpression', () => {
 describe('parseSchedule', () => {
   it('parses duration to interval mode', async () => {
     const result = await parseSchedule('5m')
-    expect(result).toEqual({
-      spec: { mode: 'interval', intervalMs: 300_000 },
-    })
+    expect(result).toEqual({ mode: 'interval', intervalMs: 300_000 })
   })
 
   it('returns undefined for invalid duration', async () => {
@@ -119,7 +117,7 @@ describe('parseSchedule', () => {
   it('parses valid cron expression to cron mode', async () => {
     const result = await parseSchedule('0 9 * * 1-5')
     expect(result).toBeDefined()
-    expect(result!.spec.mode).toBe('cron')
+    expect(result!.mode).toBe('cron')
   })
 
   it('returns undefined for invalid cron with spaces', async () => {

package/src/__tests__/property.test.ts

@@ -84,7 +84,7 @@ describe('property: parseDuration/parseSchedule round-trip', () => {
           // 无空格字符串 → 恒走 duration 分支 → interval mode + 同一 intervalMs
           const parsed = await parseSchedule(text)
           expect(parsed).toBeDefined()
-          expect(parsed!.spec).toEqual({ mode: 'interval', intervalMs: expectedMs })
+          expect(parsed!).toEqual({ mode: 'interval', intervalMs: expectedMs })
         },
       ),
     )

package/src/__tests__/replay.test.ts

@@ -37,7 +37,6 @@ function snapshot(overrides: Partial<TaskSnapshot> = {}): TaskSnapshot {
     kind: 'recurring',
     schedule: { mode: 'interval', intervalMs: 60000 },
     enabled: true,
-    force: false,
     createdAt: 0,
     nextRunAt: 100,
     runCount: 0,