@zhushanwen/pi-scheduler 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "main": "index.ts",
   "pi": {
@@ -15,6 +15,7 @@
     "pi-package"
   ],
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
     "fast-check": "^4.9.0",
     "vitest": "^4.1.8"
   },

package/src/__tests__/sdk-contract.test.ts

@@ -5,14 +5,16 @@
 //   1. tool 注册名为 schedule / schedule_control
 //   2. tool 有 execute 函数字段（不是 handler/fn）
 //   3. execute 是 async function（SDK 期望返回 Promise）
-//   4. handler 抛错被 catch 转为 { isError: true }（standards.md §4.2 禁止抛）
+//   4. 错误路径 throw（W4：pi-agent-core 只对 execute throw 置 isError:true，
+//      返回值里的 isError 字段被 agent-loop 丢弃——错误轮曾被标成功；
+//      锚点 agent-loop.js:453-483/525-547）
 //
 // 不导入 SchedulerRuntime 的内部：只通过 index.ts 的 default export 测，
 // 保证 tool 注册逻辑的入口契约。
 //
 // 关键回归点：runtime 在 session_start 前为 null。execute 通过 getRuntime() 延迟
 // 读取——若在 factory 顶层捕获 runtime! 非空断言，注册时 runtime 为 null，
-// execute 调用会 NPE。此套件验证 session_start 前 execute 优雅返回 isError 而非 crash。
+// execute 调用会 NPE。此套件验证 session_start 前 execute 优雅 throw 而非 crash。
 
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { describe, expect, it, vi } from 'vitest'
@@ -21,7 +23,7 @@ import { describe, expect, it, vi } from 'vitest'
 // 会触碰真实用户 FS（~/.pi/agent/scheduler/root/test/scheduler.json 的 renameSync/existsSync/
 // unlinkSync；该目录是活跃数据目录，一旦路径存在会 rename+unlink 真实用户数据且结果不确定）。
 // mock 掉 importer 模块：session_start 装配路径仍被调用（vi.fn 记录调用），FS 副作用为零；
-// 装配时序由 tools/verify-scheduler-e2e.cjs 的 S10/S12/S17 真实环境覆盖。
+// 装配时序由 scripts/verify-scheduler-e2e.cjs 的 S10/S12/S17 真实环境覆盖。
 // mock 返回 vi.fn() 作为延迟删除 cleanup（MF-1：turn_end / session_shutdown 装配链路可测）。
 vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
 
@@ -111,7 +113,7 @@ describe('pi-scheduler SDK contract', () => {
     }
   })
 
-  it('session_start 前 execute 抛错返回 isError（runtime 未初始化）', async () => {
+  it('session_start 前 execute throw（runtime 未初始化；W4：pi 只采信 throw）', async () => {
     const { pi, tools, events } = createMockPi()
     schedulerExtension(pi)
     const fakeCtx = createFakeCtx()
@@ -119,12 +121,10 @@ describe('pi-scheduler SDK contract', () => {
     // 不触发 session_start，runtime 仍为 null
     expect(events.get('session_start')).toBeDefined()
 
-    const result = await tools[0]!.execute('call-1', { prompt: 'x', schedule: '5m' }, undefined, undefined, fakeCtx)
-    expect(result).toEqual({
-      content: [{ type: 'text', text: 'Error: Scheduler not initialized: session not started' }],
-      details: {},
-      isError: true,
-    })
+    // W4：错误 throw 传播——pi catch 后置 isError:true，文案（含 Error: 前缀格式，R3）进 toolResult
+    await expect(
+      tools[0]!.execute('call-1', { prompt: 'x', schedule: '5m' }, undefined, undefined, fakeCtx),
+    ).rejects.toThrow('Error: Scheduler not initialized: session not started')
   })
 
   it('session_start 后 execute 正常返回结果', async () => {
@@ -153,31 +153,30 @@ describe('pi-scheduler SDK contract', () => {
     expect(result.isError).toBeFalsy()
   })
 
-  it('handler 返回结构化失败被 isError 标记（而非 throw）—— standards.md §4.2 契约', async () => {
+  it('handler 业务失败 throw（W4：返回值 isError 被 pi 丢弃，throw 才被采信）', async () => {
     const { pi, tools, events } = createMockPi()
     schedulerExtension(pi)
     const fakeCtx = createFakeCtx()
     await events.get('session_start')!({ type: 'session_start', reason: 'startup' }, fakeCtx)
 
-    // 非法 cron 表达式：service.create 返回 INVALID_SCHEDULE 结构化失败，
-    // handler 返回 isError result（text 为 service message 本体，无 'Error:' 前缀）。
-    const result = await tools[0]!.execute('call-err', { prompt: 'x', schedule: 'invalid-cron-expr-xxx' }, undefined, undefined, fakeCtx)
-    expect(result.isError).toBe(true)
-    expect(result.content[0].text).toContain('Invalid schedule')
-    expect(result.content[0].text).not.toContain('Error:')
+    // 非法 cron 表达式：service.create 失败 → toToolResult throw service message 本体
+    //（无 'Error:' 前缀——前缀格式仅 index.ts 的初始化异常兜底使用）
+    await expect(
+      tools[0]!.execute('call-err', { prompt: 'x', schedule: 'invalid-cron-expr-xxx' }, undefined, undefined, fakeCtx),
+    ).rejects.toThrow('Invalid schedule')
   })
 
-  it('schedule_control tool 同样返回结构化 isError', async () => {
+  it('schedule_control tool 业务失败同样 throw（W4）', async () => {
     const { pi, tools, events } = createMockPi()
     schedulerExtension(pi)
     const fakeCtx = createFakeCtx()
     await events.get('session_start')!({ type: 'session_start', reason: 'startup' }, fakeCtx)
 
-    // toggle 不存在的 task id：service 返回 TASK_NOT_FOUND，handler 返回 isError
+    // toggle 不存在的 task id：service 返回 TASK_NOT_FOUND → throw message 本体
     const controlTool = tools.find(t => t.name === 'schedule_control')!
-    const result = await controlTool.execute('call-ctrl', { action: 'toggle', id: 'deadbeef', enabled: false }, undefined, undefined, fakeCtx)
-    expect(result.isError).toBe(true)
-    expect(result.content[0].text).toBe('Task deadbeef not found.')
+    await expect(
+      controlTool.execute('call-ctrl', { action: 'toggle', id: 'deadbeef', enabled: false }, undefined, undefined, fakeCtx),
+    ).rejects.toThrow('Task deadbeef not found.')
   })
 
   it('registerCommand 注册了名为 schedule 的命令', () => {

package/src/__tests__/service.test.ts

@@ -12,6 +12,9 @@ describe('SchedulerService', () => {
 
   beforeEach(() => {
     backend = new MockSchedulerBackend()
+    // 固定时间避免 clock-boundary flake：formatRelativeTime 内部读 Date.now()，
+    // 两次读之间的延迟可能导致 "in 1h" 变成 "in 59m"。
+    backend.nowValue = Date.now()
     service = new SchedulerService(new SchedulerRuntime(backend, mockCtx), () => backend.now())
   })
 

package/src/__tests__/tool.test.ts

@@ -25,12 +25,12 @@ describe('schedule tool', () => {
     expect(details.task.schedule).toEqual({ mode: 'interval', intervalMs: 300000 })
   })
 
-  it('invalid schedule returns isError with message (not throw)', async () => {
-    const result = await handler({ prompt: 'test', schedule: 'invalid' })
-    expect(result.isError).toBe(true)
-    expect(result.content[0]!.text).toContain('Invalid schedule')
-    const details = result.details as { errorCode: string }
-    expect(details.errorCode).toBe('INVALID_SCHEDULE')
+  // W4：业务失败 throw（pi 只对 execute throw 置 isError:true，返回值里的 isError
+  // 被 agent-loop 丢弃——错误轮曾被标成功）。原 errorCode details 随 throw 不再产出。
+  it('invalid schedule throws with message (W4: pi 采信 throw)', async () => {
+    await expect(handler({ prompt: 'test', schedule: 'invalid' })).rejects.toThrow(
+      'Invalid schedule',
+    )
   })
 })
 
@@ -62,19 +62,17 @@ describe('schedule_control tool', () => {
     expect(result.content[0]!.text).toContain('disabled')
   })
 
-  it('missing id on toggle returns isError', async () => {
-    const result = await handler({ action: 'toggle', enabled: true })
-    expect(result.isError).toBe(true)
-    expect(result.content[0]!.text).toContain('id is required')
+  it('missing id on toggle throws (W4)', async () => {
+    await expect(handler({ action: 'toggle', enabled: true })).rejects.toThrow(
+      'id is required',
+    )
   })
 
-  // TC5 tool 侧：toggle 不存在 id → 结构化 isError + TASK_NOT_FOUND
-  it('TC5: toggle unknown id returns isError with TASK_NOT_FOUND', async () => {
-    const result = await handler({ action: 'toggle', id: 'deadbeef', enabled: false })
-    expect(result.isError).toBe(true)
-    const details = result.details as { errorCode: string }
-    expect(details.errorCode).toBe('TASK_NOT_FOUND')
-    expect(result.content[0]!.text).toBe('Task deadbeef not found.')
+  // TC5 tool 侧：toggle 不存在 id → throw（service message 原文即 TASK_NOT_FOUND 文案）
+  it('TC5: toggle unknown id throws with TASK_NOT_FOUND message (W4)', async () => {
+    await expect(handler({ action: 'toggle', id: 'deadbeef', enabled: false })).rejects.toThrow(
+      'Task deadbeef not found.',
+    )
   })
 
   it('deletes task', async () => {

package/src/index.ts

@@ -113,8 +113,9 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
 
   // 注册 schedule tool
   // execute 内联闭包：从 SDK 全签名 (toolCallId, params, signal, onUpdate, ctx) 提取 params 转调
-  // handler。catch 兜底 INTERNAL + 未初始化异常（R3：handler 不 catch getService()，
-  // 初始化异常穿透到这里，保持 'Error: Scheduler not initialized' 格式）。
+  // handler。错误路径 throw（W4）：pi 只对 execute throw 置 isError:true（返回值里的
+  // isError 被 agent-loop 丢弃）；getService() 未初始化异常穿透到这里，包装
+  // 'Error: Scheduler not initialized' 格式（R3 格式保持）。
   pi.registerTool({
     name: 'schedule',
     label: 'Schedule',
@@ -131,16 +132,12 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
       try {
         return await createScheduleHandler(getService())(params)
       } catch (err) {
-        return {
-          content: [{ type: 'text' as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
-          details: {},
-          isError: true,
-        }
+        throw new Error(`Error: ${err instanceof Error ? err.message : String(err)}`)
       }
     },
   })
 
-  // 注册 schedule_control tool
+  // 注册 schedule_control tool（错误路径同上：throw 让 pi 置 isError）
   pi.registerTool({
     name: 'schedule_control',
     label: 'Schedule Control',
@@ -157,11 +154,7 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
       try {
         return await createScheduleControlHandler(getService())(params)
       } catch (err) {
-        return {
-          content: [{ type: 'text' as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
-          details: {},
-          isError: true,
-        }
+        throw new Error(`Error: ${err instanceof Error ? err.message : String(err)}`)
       }
     },
   })

package/src/service.ts

@@ -71,19 +71,21 @@ export class SchedulerService {
     }
 
     const count = task.kind === 'once' ? 1 : PREVIEW_RUN_COUNT
-    const nextRuns = await computeNextRuns(task.schedule, this.now(), count)
+    // 消息内相对时间与 nextRuns 必须同基准：分开读时钟会在整点边界漂移（in 1h → in 59m）
+    const now = this.now()
+    const nextRuns = await computeNextRuns(task.schedule, now, count)
     // once 单行内联回显（只执行 1 次，编号列表会误导）；recurring 保持 5 行编号列表
     const runPreview =
       task.kind === 'once'
-        ? `Next run: ${formatRelativeTime(nextRuns[0]!)}`
+        ? `Next run: ${formatRelativeTime(nextRuns[0]!, now)}`
         : [
             'Next 5 runs:',
-            ...nextRuns.map((t, i) => `  ${i + 1}. ${formatRelativeTime(t)}`),
+            ...nextRuns.map((t, i) => `  ${i + 1}. ${formatRelativeTime(t, now)}`),
           ].join('\n')
     // 一行紧凑：name(id) + schedule(含 kind 信息) + expires + force。
     // 删冗余 Kind 行（formatSchedule 已含 once/every）；Expires/Force 合并（默认 no-expires/no-force 显式）。
     const expiresLabel = task.expiresAt
-      ? `expires ${formatRelativeTime(task.expiresAt)}`
+      ? `expires ${formatRelativeTime(task.expiresAt, now)}`
       : 'no-expires'
     const forceLabel = task.force ? 'force' : 'no-force'
     const message = [
@@ -99,8 +101,10 @@ export class SchedulerService {
     if (tasks.length === 0) {
       return { success: true, message: 'No scheduled tasks.', data: { tasks: [] } }
     }
+    // 同 create：同一基准渲染全部相对时间，避免逐项读时钟的边界漂移
+    const now = this.now()
     const message = tasks.map(t =>
-      `${t.enabled ? '●' : '○'} ${t.id} ${t.name} · ${formatSchedule(t.schedule, t.kind)} · ${formatRelativeTime(t.nextRunAt)}`
+      `${t.enabled ? '●' : '○'} ${t.id} ${t.name} · ${formatSchedule(t.schedule, t.kind)} · ${formatRelativeTime(t.nextRunAt, now)}`
     ).join('\n')
     return { success: true, message, data: { tasks } }
   }

package/src/tool.ts

@@ -27,8 +27,9 @@ export const scheduleGuidelines = [
 
 /**
  * schedule tool handler（SchedulerService 瘦壳，无独立业务逻辑）。
- * 业务失败 → 结构化 isError result（不 throw）；service 未初始化等初始化异常
- * 不在此 catch——穿透到 index.ts execute 的 catch 兜底（R3）。
+ * 业务失败 → throw（pi 只对 execute throw 置 isError:true，返回值里的 isError
+ * 被 agent-loop 丢弃——W4 修复，锚点 agent-loop.js:453-483）；service 未初始化等
+ * 初始化异常不在此 catch——穿透到 index.ts execute 的 catch 兜底（R3）。
  */
 export function createScheduleHandler(service: SchedulerService) {
   return async (params: ScheduleParamsT) => {
@@ -86,19 +87,16 @@ export function createScheduleControlHandler(service: SchedulerService) {
 
 /**
  * ServiceResult → tool execute 返回。
- * 成功 → {content: [message], details: data}；失败 → isError + details.errorCode。
+ * 成功 → {content: [message], details: data}；失败 → throw（W4：pi 契约只有
+ * execute throw 才置 isError:true，pi catch 后 message 原样成为 toolResult content，
+ * 错误轮不再被标成功）。
  */
 function toToolResult(result: ServiceResult): {
   content: { type: 'text'; text: string }[]
   details: unknown
-  isError?: boolean
 } {
   if (!result.success) {
-    return {
-      content: [{ type: 'text' as const, text: result.message }],
-      details: { errorCode: result.errorCode },
-      isError: true,
-    }
+    throw new Error(result.message)
   }
   return {
     content: [{ type: 'text' as const, text: result.message }],