@zhushanwen/pi-scheduler 0.3.2 → 0.3.4

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "type": "module",
   "main": "index.ts",
+  "xyz-agent": {
+    "role": "universal"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -15,6 +18,7 @@
     "pi-package"
   ],
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
     "fast-check": "^4.9.0",
     "vitest": "^4.1.8"
   },
@@ -25,7 +29,7 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
     "croner": "^9.0.0",
     "typebox": "*"
   },

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'
@@ -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__/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/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 }],