@zhushanwen/pi-scheduler 0.4.3 → 0.5.0

package/README.md

@@ -57,7 +57,7 @@ session_start
 
 ## /schedule 命令用法
 
-注册为 `/schedule` 命令。无参数时显示 usage；第一个参数匹配子命令关键词则走子命令分支，否则尝试创建任务。
+注册为 `/schedule` 命令。无参数时返回 TUI 未实现提示（用 `/schedule list` 查看任务）；第一个参数匹配子命令关键词则走子命令分支，否则尝试创建任务。
 
 ### 子命令
 
@@ -90,7 +90,7 @@ session_start
 
 ### duration（间隔调度）
 
-`<数字><单位>`，数字与单位间可有空格，**大小写不敏感**：
+`<数字><单位>`，数字与单位间不留空格，**大小写不敏感**：
 
 | 单位 | 含义 | 乘数 |
 |------|------|------|
@@ -163,14 +163,14 @@ session_start
 | 默认过期 | **7 天**（`DEFAULT_EXPIRY_MS`） | recurring 任务缺省 `expires` 时；`expires: 'never'` 关闭 |
 | once 任务 | 触发后自动删除 | 不参与后续调度 |
 | cron 失效 | 任务停用 + `lastStatus=failed` + `lastError='cron expression invalid'` | 不会用 `now()` 兜底导致每 tick 重触发死循环 |
-| 忙时 dispatch | 非 force 任务在 agent 忙（非 idle / 有 pending 消息）时跳过，延迟到下次 tick | force=true 可绕过 |
+| 忙时 dispatch | 非 force 任务经 session delivery 内核 park 模式：忙时消息入队等待（等 agent 空闲的 settled 边沿 / 下个 tick flush 投递），不丢弃 | force=true 绕过内核队列直投 |
 | history | 保留最近 **20** 条执行记录 | 超出丢弃最旧；重放折叠时同样裁剪 |
 | 持久化 | custom entry append 到 session JSONL（dispatch 成功后立即 append advance 记录执行） | 任务随 owner session 持久化，resume 后重放恢复，无需额外写盘 |
 | 交付语义 | **at-least-once**（至少一次） | dispatch 成功后内存更新 nextRunAt 并 append advance；append 之前若进程崩溃可能重复注入一次（无精确一次保证，可接受） |
 | 延迟写入窗口 | 新 session 首 turn 内建任务后进程崩溃可能丢失 | pi 延迟写入：首条 assistant 消息前不 flush。窗口窄、概率极低、无恢复手段 |
 | 触发条件 | pi 进程需存活且 session 打开 | 电脑睡眠 / pi 进程未运行 = 不触发（非系统 cron，无后台守护） |
 
-错误语义：创建时 schedule 解析失败 → `INVALID_SCHEDULE`；`run`/`toggle`/`delete` 引用不存在的 id → `TASK_NOT_FOUND`；`run` 时任务 disabled / busy / rate-limited → `DISPATCH_SKIPPED`（message 含 `busy, disabled, or rate-limited`）。
+错误语义：创建时 schedule 解析失败 → `INVALID_SCHEDULE`；`run`/`toggle`/`delete` 引用不存在的 id → `TASK_NOT_FOUND`；`run` 时任务 disabled / rate-limited / 同任务已在投递队列（TTL 窗口内）→ `DISPATCH_SKIPPED`（message 含 `disabled, rate-limited, or already queued for delivery`）。
 
 ## 数据存储位置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.3.1"
+    "@zhushanwen/pi-extension-logger": "0.4.0"
   },
   "scripts": {
     "test": "vitest run",

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

@@ -33,7 +33,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 
 - **`schedule`**（创建）：参数 `prompt`（必填，到期注入的消息）、`schedule`（必填，duration 或 cron）、`kind`（`once`/`recurring`，默认 `recurring`）、`name`（可选，缺省从 prompt 自动截取前 30 字）、`expires`（可选，默认 7 天；传 `"never"` 关闭过期）、`force`（可选，默认 `false`）。
 - **`schedule_control`**（管理）：`action` = `list`/`toggle`/`delete`/`run`，`id`（toggle/delete/run 必填），`enabled`（toggle 必填）。
-- 两个工具的返回都是结构化 `{content: [{type:'text', text}], details, isError?}`，业务失败返回 `isError:true` + `details.errorCode`（不抛异常）。
+- 两个工具的返回都是结构化 `{content: [{type:'text', text}], details}`；业务失败以异常抛出（pi 只对 execute throw 置 `isError:true`，错误 message 作为 toolResult content 返回），不通过返回值表达失败。
 
 > 创建/管理操作无需 agent idle——只有**到期 dispatch** 才受 idle/速率限制约束（见「运行限制与 dispatch 行为」）。
 
@@ -52,7 +52,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 | `h` | `hr`/`hour`/`hours` | 3_600_000 |
 | `d` | `day`/`days` | 86_400_000 |
 
-示例：`5m`、`2h`、`1d`、`30seconds`。正则 `/^(\d+)\s*(s|sec|...)$/i`，不匹配则解析失败。
+示例：`5m`、`2h`、`1d`、`30seconds`。正则 `/^(\d+)\s*(s|sec|...)$/i`（注意：含空格的输入在 parseSchedule 分流时一律走 cron 分支，duration 实际不允许空格，`5 m` 解析失败）。
 
 ### cron（cron 表达式）
 
@@ -119,7 +119,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 
 dispatch 触发条件（`dispatchTask`）：
 
-- **非 force 任务**：仅在 `ctx.isIdle() && !ctx.hasPendingMessages()` 时触发；否则**延迟到下个 tick**（不丢弃，标记 `pending`，下个 30s tick 重试）。
+- **非 force 任务**：走统一 session delivery 内核（park 模式）——到期即入队，agent 忙时消息 park 在内核队列，等 agent 空闲的 settled 边沿投递，scheduler 每 30s tick 触发一次 flush 兜底重试；不丢弃。
 - **force=true 任务**：即使 agent busy 也立即触发（用于必须准点执行的场景）。
 - dispatch 成功后：recurring 推进 `nextRunAt` 并 append `advance`；once 删除任务并 append `delete`；失败（`sendMessage` 抛错）记 `lastStatus='failed'` 不 rethrow，下个 tick 重试（transient 失败重试语义，不 append advance）。
 - 注入的消息：`{content: task.prompt, customType: 'pi-scheduler:dispatched', display: true}`，`deliverAs: 'followUp'` + `triggerTurn: true`（排进 followUp 队列并唤醒 agent 开新 turn）。
@@ -137,7 +137,7 @@ dispatch 触发条件（`dispatchTask`）：
 - `force`：是否在 agent busy 时强制 dispatch。
 - `createdAt` / `nextRunAt` / `expiresAt?`：时间戳（ms）。
 - `runCount` / `lastRunAt?` / `lastStatus?`（`success`|`failed`）/ `lastError?`：执行统计。
-- `history`：最近 20 条 `ExecutionRecord`（`{at, status, snippet?}`，snippet 为 agent 回复前 100 字）。
+- `history`：最近 20 条 `ExecutionRecord`（`{at, status}`）。
 - `ownerSessionFile?`：归属 session JSONL 路径（fork 过滤用，非持久化业务字段）。
 - `pending?`：运行时标记「到期待 dispatch」，非持久化（与 `enabled` 正交）。
 

package/src/__tests__/cron.test.ts

@@ -58,7 +58,7 @@ describe('computeNextCronRuns', () => {
 })
 
 describe('parseSchedule (cron 分支)', () => {
-  it('5 字段 cron 表达式补秒字段（note 不再透传到 parseSchedule 结果）', async () => {
+  it('5 字段 cron 表达式补秒字段', async () => {
     const result = await parseSchedule('*/10 * * * *')
     expect(result).toEqual({
       spec: { mode: 'cron', cronExpression: '0 */10 * * * *' },
@@ -85,8 +85,7 @@ describe('parseSchedule (cron 分支)', () => {
 
 describe('normalizeCronExpression', () => {
   it('6 字段 cron 原样返回', () => {
-    const result = normalizeCronExpression('0 9 * * 1-5 0')
-    expect(result).toEqual({ expression: '0 9 * * 1-5 0' })
+    expect(normalizeCronExpression('0 9 * * 1-5 0')).toBe('0 9 * * 1-5 0')
   })
 
   it('2 字段返回 undefined', () => {

package/src/__tests__/parsing.test.ts

@@ -84,16 +84,11 @@ describe('formatDuration', () => {
 
 describe('normalizeCronExpression', () => {
   it('prepends seconds field for 5-field cron', () => {
-    const result = normalizeCronExpression('*/10 * * * *')
-    expect(result).toEqual({
-      expression: '0 */10 * * * *',
-      note: 'Auto-prepended seconds field (0)',
-    })
+    expect(normalizeCronExpression('*/10 * * * *')).toBe('0 */10 * * * *')
   })
 
   it('keeps 6-field cron as-is', () => {
-    const result = normalizeCronExpression('0 */10 * * * *')
-    expect(result).toEqual({ expression: '0 */10 * * * *' })
+    expect(normalizeCronExpression('0 */10 * * * *')).toBe('0 */10 * * * *')
   })
 
   it('returns undefined for invalid field count', () => {

package/src/__tests__/service.test.ts

@@ -191,7 +191,7 @@ describe('SchedulerService', () => {
       expect(result).toEqual({
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
+        message: `Task ${id} not dispatched (disabled, rate-limited, or already queued for delivery).`,
       })
     })
 

package/src/commands.ts

@@ -48,7 +48,7 @@ export function registerScheduleCommand(
   getService: () => SchedulerService | null,
 ) {
   pi.registerCommand('schedule', {
-    description: 'Manage scheduled tasks. No args opens TUI. /schedule <schedule> <prompt> to create.',
+    description: 'Manage scheduled tasks. /schedule <schedule> <prompt> to create; /schedule list to see tasks.',
     getArgumentCompletions(prefix: string) {
       const service = getService()
       const trimmed = prefix.trimStart()

package/src/format.ts

@@ -82,14 +82,10 @@ export function generateTaskId(): string {
 
 /** autoName 任务名最大长度。 */
 const AUTO_NAME_MAX_LENGTH = 30
-/** 截断后保留的长度（预留省略号宽度）。 */
-const AUTO_NAME_KEEP_LENGTH = AUTO_NAME_MAX_LENGTH - ELLIPSIS_LENGTH
 
 /**
  * 从 prompt 自动生成任务名称：取前 30 字。
  */
 export function autoName(prompt: string): string {
-  const trimmed = prompt.trim()
-  if (trimmed.length <= AUTO_NAME_MAX_LENGTH) return trimmed
-  return trimmed.slice(0, AUTO_NAME_KEEP_LENGTH) + '...'
+  return truncate(prompt.trim(), AUTO_NAME_MAX_LENGTH)
 }

package/src/parsing.ts

@@ -82,7 +82,7 @@ async function getCroner(): Promise<typeof import('croner') | null> {
  * 规范化 cron 表达式：5 字段自动补秒字段。
  * 返回 undefined 表示无效。
  */
-export function normalizeCronExpression(input: string): { expression: string; note?: string } | undefined {
+export function normalizeCronExpression(input: string): string | undefined {
   const trimmed = input.trim()
   if (!trimmed) return undefined
 
@@ -90,15 +90,12 @@ export function normalizeCronExpression(input: string): { expression: string; no
 
   // 6 字段原样返回
   if (parts.length === CRON_FIELD_COUNT_WITH_SECONDS) {
-    return { expression: trimmed }
+    return trimmed
   }
 
   // 5 字段补秒字段
   if (parts.length === CRON_FIELD_COUNT) {
-    return {
-      expression: `0 ${trimmed}`,
-      note: 'Auto-prepended seconds field (0)',
-    }
+    return `0 ${trimmed}`
   }
 
   return undefined
@@ -119,7 +116,7 @@ export async function computeNextCronRunAt(
     const normalized = normalizeCronExpression(expression)
     if (!normalized) return undefined
 
-    const job = new croner.Cron(normalized.expression, { startAt: from ? new Date(from) : undefined })
+    const job = new croner.Cron(normalized, { startAt: from ? new Date(from) : undefined })
     const next = job.nextRun()
     return next ? next.getTime() : undefined
   } catch {
@@ -143,7 +140,7 @@ export async function computeNextCronRuns(
     const normalized = normalizeCronExpression(expression)
     if (!normalized) return []
 
-    const job = new croner.Cron(normalized.expression, { startAt: from ? new Date(from) : undefined })
+    const job = new croner.Cron(normalized, { startAt: from ? new Date(from) : undefined })
     const runs: number[] = []
     let current = from ? new Date(from) : new Date()
 
@@ -192,7 +189,7 @@ export async function parseSchedule(
     const nextRun = await computeNextCronRunAt(trimmed)
     if (nextRun !== undefined) {
       return {
-        spec: { mode: 'cron', cronExpression: normalized.expression },
+        spec: { mode: 'cron', cronExpression: normalized },
       }
     }
   }

package/src/runtime.ts

@@ -505,10 +505,4 @@ export class SchedulerRuntime {
     const { ownerSessionFile: _o, pending: _p, history, ...rest } = task
     return { ...rest, history: history.slice() }
   }
-
-  // ── 工具方法 ──
-
-  getTaskCount(): number {
-    return this.tasks.size
-  }
 }

package/src/service.ts

@@ -137,7 +137,8 @@ export class SchedulerService {
   /**
    * 立即执行任务。语义细分：
    * 任务不存在 → TASK_NOT_FOUND；任务存在但 dispatch no-op
-   * （disabled / busy / rate-limited / 同任务 dispatch 在途）→ DISPATCH_SKIPPED。
+   * （disabled / rate-limited / 同任务入队已在 TTL 窗口内）→ DISPATCH_SKIPPED。
+   * busy 不再是 no-op：非 force 任务入队 delivery 内核即成功（park 等后续投递）。
    * 修复了旧实现把 no-op 误报为 not found 的混同。
    */
   async run(id: string | undefined): Promise<ServiceResult> {
@@ -152,7 +153,7 @@ export class SchedulerService {
       return {
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
+        message: `Task ${id} not dispatched (disabled, rate-limited, or already queued for delivery).`,
       }
     }
     return { success: true, message: `Task ${id} executed.` }

package/src/tool.ts

@@ -11,7 +11,7 @@ export const ScheduleParams = Type.Object({
   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.' })),
+  expires: Type.Optional(Type.String({ description: 'Expiry duration (30m/2h/7d). Default: 7d. Pass "never" to disable. Only applies to recurring tasks (once tasks fire and are removed, expires is ignored).' })),
   force: Type.Optional(Type.Boolean({ description: 'Dispatch even when agent is busy. Default: false.' })),
 })
 
@@ -53,7 +53,7 @@ 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.',
+  'action="run" dispatches the task now: force tasks are sent directly; non-force tasks are enqueued via the delivery kernel and delivered once the agent is idle (busy messages wait in the queue and are flushed later).',
 ]
 
 export function createScheduleControlHandler(service: SchedulerService) {

package/src/types.ts

@@ -32,7 +32,6 @@ export interface ScheduledTask {
 export interface ExecutionRecord {
   at: number
   status: TaskStatus
-  snippet?: string                  // agent 回复前 100 字
 }
 
 // ── CustomEntry event sourcing（append-only 任务存储）──