@zhushanwen/pi-scheduler 0.4.2 → 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.2",
+  "version": "0.5.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -29,7 +29,7 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
     "croner": "^9.0.0",
     "typebox": "*"
   },
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.3.0"
+    "@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

@@ -1,6 +1,11 @@
-import { formatDuration } from './parsing.js'
+import { formatDuration, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND } from './parsing.js'
 import type { ScheduleSpec, TaskKind } from './types.js'
 
+/** 相对时间显示的"现在"判定窗口（±5s 内视为 now）。 */
+const NOW_THRESHOLD_MS = 5000
+/** 省略号 "..." 的字符数（truncate 截断预留宽度）。 */
+const ELLIPSIS_LENGTH = 3
+
 /** Format ScheduleSpec to readable string. kind 区分 once/recurring（once 显示 'once in X' 而非误导性的 'every X'）。 */
 export function formatSchedule(spec: ScheduleSpec, kind?: TaskKind): string {
   if (spec.mode === 'interval') {
@@ -25,14 +30,14 @@ export function formatRelativeTime(timestamp: number, now?: number): string {
   const diff = timestamp - currentTime
 
   // 5秒内视为"现在"
-  if (Math.abs(diff) < 5000) return 'now'
+  if (Math.abs(diff) < NOW_THRESHOLD_MS) return 'now'
 
   const absDiff = Math.abs(diff)
   const units: [string, number][] = [
-    ['d', 86_400_000],
-    ['h', 3_600_000],
-    ['m', 60_000],
-    ['s', 1000],
+    ['d', MS_PER_DAY],
+    ['h', MS_PER_HOUR],
+    ['m', MS_PER_MINUTE],
+    ['s', MS_PER_SECOND],
   ]
 
   let formatted = ''
@@ -45,7 +50,7 @@ export function formatRelativeTime(timestamp: number, now?: number): string {
   }
 
   if (!formatted) {
-    formatted = `${Math.round(absDiff / 1000)}s`
+    formatted = `${Math.round(absDiff / MS_PER_SECOND)}s`
   }
 
   return diff > 0 ? `in ${formatted}` : `${formatted} ago`
@@ -56,24 +61,31 @@ export function formatRelativeTime(timestamp: number, now?: number): string {
  */
 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) + '...'
+  if (maxLen <= ELLIPSIS_LENGTH) return text.slice(0, maxLen)
+  return text.slice(0, maxLen - ELLIPSIS_LENGTH) + '...'
 }
 
+/** 生成任务 ID 的随机字节数（8 位 hex = 4 字节）。 */
+const TASK_ID_RANDOM_BYTES = 4
+const HEX_RADIX = 16
+/** 每字节展开的 hex 字符数（padStart 宽度）。 */
+const HEX_CHARS_PER_BYTE = 2
+
 /**
  * 生成任务 ID：8 位 hex。
  */
 export function generateTaskId(): string {
-  const bytes = new Uint8Array(4)
+  const bytes = new Uint8Array(TASK_ID_RANDOM_BYTES)
   crypto.getRandomValues(bytes)
-  return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('')
+  return Array.from(bytes, b => b.toString(HEX_RADIX).padStart(HEX_CHARS_PER_BYTE, '0')).join('')
 }
 
+/** autoName 任务名最大长度。 */
+const AUTO_NAME_MAX_LENGTH = 30
+
 /**
  * 从 prompt 自动生成任务名称：取前 30 字。
  */
 export function autoName(prompt: string): string {
-  const trimmed = prompt.trim()
-  if (trimmed.length <= 30) return trimmed
-  return trimmed.slice(0, 27) + '...'
+  return truncate(prompt.trim(), AUTO_NAME_MAX_LENGTH)
 }

package/src/parsing.ts

@@ -2,13 +2,19 @@ import type { ParseScheduleResult, ScheduleSpec } from './types.js'
 
 // ── Duration 解析 ──
 
+// 时间单位毫秒数（包内共享：format.ts / runtime.ts 复用）
+export const MS_PER_DAY = 86_400_000
+export const MS_PER_HOUR = 3_600_000
+export const MS_PER_MINUTE = 60_000
+export const MS_PER_SECOND = 1000
+
 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,
+  s: MS_PER_SECOND, sec: MS_PER_SECOND, second: MS_PER_SECOND, seconds: MS_PER_SECOND,
+  m: MS_PER_MINUTE, min: MS_PER_MINUTE, minute: MS_PER_MINUTE, minutes: MS_PER_MINUTE,
+  h: MS_PER_HOUR, hr: MS_PER_HOUR, hour: MS_PER_HOUR, hours: MS_PER_HOUR,
+  d: MS_PER_DAY, day: MS_PER_DAY, days: MS_PER_DAY,
 }
 
 /**
@@ -34,10 +40,10 @@ 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],
+    ['d', MS_PER_DAY],
+    ['h', MS_PER_HOUR],
+    ['m', MS_PER_MINUTE],
+    ['s', MS_PER_SECOND],
   ]
 
   for (const [suffix, divisor] of units) {
@@ -47,11 +53,18 @@ export function formatDuration(ms: number): string {
   }
 
   // 兜底：用秒表示
-  return `${Math.round(ms / 1000)}s`
+  return `${Math.round(ms / MS_PER_SECOND)}s`
 }
 
 // ── Cron 解析 ──
 
+/** cron 标准字段数（分 时 日 月 周）。 */
+const CRON_FIELD_COUNT = 5
+/** 带秒字段的标准 cron 字段数（秒 分 时 日 月 周）。 */
+const CRON_FIELD_COUNT_WITH_SECONDS = 6
+/** computeNextCronRuns / computeNextRuns 默认返回的未来执行时间数。 */
+const DEFAULT_NEXT_RUNS_COUNT = 5
+
 let cronerModule: typeof import('croner') | null | undefined
 
 async function getCroner(): Promise<typeof import('croner') | null> {
@@ -69,23 +82,20 @@ 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
 
   const parts = trimmed.split(/\s+/)
 
   // 6 字段原样返回
-  if (parts.length === 6) {
-    return { expression: trimmed }
+  if (parts.length === CRON_FIELD_COUNT_WITH_SECONDS) {
+    return trimmed
   }
 
   // 5 字段补秒字段
-  if (parts.length === 5) {
-    return {
-      expression: `0 ${trimmed}`,
-      note: 'Auto-prepended seconds field (0)',
-    }
+  if (parts.length === CRON_FIELD_COUNT) {
+    return `0 ${trimmed}`
   }
 
   return undefined
@@ -106,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 {
@@ -121,7 +131,7 @@ export async function computeNextCronRunAt(
 export async function computeNextCronRuns(
   expression: string,
   from?: number,
-  count = 5,
+  count = DEFAULT_NEXT_RUNS_COUNT,
 ): Promise<number[]> {
   const croner = await getCroner()
   if (!croner) return []
@@ -130,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()
 
@@ -179,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 },
       }
     }
   }
@@ -215,7 +225,7 @@ export async function computeNextRunAt(
 export async function computeNextRuns(
   spec: ScheduleSpec,
   from?: number,
-  count = 5,
+  count = DEFAULT_NEXT_RUNS_COUNT,
 ): Promise<number[]> {
   if (spec.mode === 'interval') {
     const start = from ?? Date.now()

package/src/runtime.ts

@@ -5,7 +5,7 @@ import type { DeliveryHandle, DeliveryMessage } from '@xyz-agent/session-deliver
 
 import type { SchedulerBackend } from './backend.js'
 import { autoName, generateTaskId } from './format.js'
-import { computeNextRunAt, parseDuration } from './parsing.js'
+import { computeNextRunAt, MS_PER_DAY, MS_PER_MINUTE, parseDuration } from './parsing.js'
 import type {
   AddOptions,
   ScheduledTask,
@@ -17,11 +17,13 @@ import type {
 const logger = getLogger('scheduler')
 
 const MAX_TASKS = 50
-// 入队防重标记 TTL（合批非首条任务无终态回调，过期后放行重投；10 min >> 合批窗口）
-const QUEUE_DEDUPE_TTL_MS = 10 * 60 * 1000
+// 入队防重标记 TTL 分钟数（合批非首条任务无终态回调，过期后放行重投；10 min >> 合批窗口）
+const QUEUE_DEDUPE_TTL_MINUTES = 10
+const QUEUE_DEDUPE_TTL_MS = QUEUE_DEDUPE_TTL_MINUTES * MS_PER_MINUTE
 const RATE_LIMIT_PER_MINUTE = 6
 const TICK_INTERVAL_MS = 30_000
-const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+const DEFAULT_EXPIRY_DAYS = 7
+const DEFAULT_EXPIRY_MS = DEFAULT_EXPIRY_DAYS * MS_PER_DAY // 7 days
 const HISTORY_LIMIT = 20 // 与 replayFoldEntries 的裁剪上限一致（advance 折叠 / dispatch 累积共用）
 // pi ExtensionRunner 在 session 替换后访问 stale ctx 时抛出的错误文案片段。
 // 兜底通道（防御纵深）：G1 模块级代际检测（isCtxStale）为主判，覆盖同模块环境内的 session
@@ -466,7 +468,7 @@ export class SchedulerRuntime {
   }
 
   private hasDispatchCapacity(now: number): boolean {
-    const oneMinuteAgo = now - 60_000
+    const oneMinuteAgo = now - MS_PER_MINUTE
     this.dispatchTimestamps = this.dispatchTimestamps.filter(t => t > oneMinuteAgo)
     return this.dispatchTimestamps.length < RATE_LIMIT_PER_MINUTE
   }
@@ -503,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 任务存储）──

package/src/widget.ts

@@ -1,6 +1,9 @@
 import { formatRelativeTime, truncate } from './format.js'
 import type { ScheduledTask } from './types.js'
 
+/** widget 中任务名的最大显示宽度（列）。 */
+const WIDGET_NAME_MAX_WIDTH = 20
+
 /**
  * 渲染 TUI status bar widget（string[]，配合 SDK setWidget 第一重载）。
  * 格式：[scheduler] 3 scheduled · check-build in 4m · 1 overdue
@@ -23,7 +26,7 @@ export function renderSchedulerWidget(tasks: ScheduledTask[]): string[] {
 
   if (upcoming.length > 0) {
     const next = upcoming[0]!
-    parts.push(`${truncate(next.name, 20)} ${formatRelativeTime(next.nextRunAt)}`)
+    parts.push(`${truncate(next.name, WIDGET_NAME_MAX_WIDTH)} ${formatRelativeTime(next.nextRunAt)}`)
   }
 
   if (overdue.length > 0) {