opencode-natural-scheduler 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lrj01232
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# opencode-natural-scheduler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Natural-language scheduled tasks for [OpenCode](https://opencode.ai). Ask for a recurring or one-off task in plain language, and the plugin schedules it, then injects the task back into the session that created it.
+
+```
+You: every 20 minutes, check the invoice service error log and summarize anomalies
+Agent: (calls schedule_create) Scheduled task created: task-... next run 2026-11-01 12:30
+```
+
+## Why another scheduler?
+
+| | opencode-natural-scheduler | opencode-scheduler | opencode-cron |
+|---|---|---|---|
+| Create tasks by asking | Yes | Cron config | Cron config |
+| Runs while OpenCode is closed | No | Yes (launchd/systemd) | No |
+| Cross-platform | Yes | macOS/Linux | Yes |
+| Injects into the originating session | Yes | Job-defined | Yes |
+| OS daemon/timer setup | None | Required | None |
+
+This plugin is intentionally in-process: no launchd, systemd, or Windows service. It is the simplest option when you want conversational scheduling inside a running OpenCode instance.
+
+## Install
+
+Add the package to your OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-natural-scheduler"]
+}
+```
+
+Or run:
+
+```bash
+opencode plugin opencode-natural-scheduler
+```
+
+Restart OpenCode after installing. The plugin starts a scheduler for each OpenCode process and elects a single leader, so multiple open windows do not fire the same task twice.
+
+## Usage
+
+Just describe the task and the schedule:
+
+- `Every 20 minutes, check the invoice module error log and report anomalies.`
+- `Every day at 09:00, summarize yesterday's failed jobs.`
+- `Remind me in 30 minutes to review the deploy.`
+- `Run this at 18:00 on weekdays: collect the daily metrics.`
+
+The agent calls `schedule_create` with a self-contained instruction, then confirms the task id and next run time.
+
+Management is conversational too:
+
+- `List my scheduled tasks.`
+- `Pause task-abc123.`
+- `Change task-abc123 to every hour.`
+- `Run task-abc123 now.`
+- `Delete task-abc123.`
+
+## Schedule types
+
+| Type | Tool argument | Example |
+|---|---|---|
+| Interval | `every_minutes` | `every_minutes: 20` |
+| Daily | `daily_at` | `daily_at: "09:30"` |
+| Cron | `cron` | `cron: "0 9 * * 1-5"` |
+| One-off | `once_at` or `once_in_minutes` | `once_in_minutes: 30` |
+
+Cron uses five fields (`minute hour day month weekday`) in the machine's local timezone. When both day-of-month and weekday are restricted, either match counts, as in standard cron.
+
+## Tools
+
+The plugin registers five tools:
+
+- `schedule_create`
+- `schedule_list`
+- `schedule_update`
+- `schedule_delete`
+- `schedule_run_now`
+
+Tools default to the current session. Pass `session_id` to target another session, or `all: true` to list every session's tasks.
+
+## Behavior details
+
+- A task is bound to the session where it was created. When it fires, the plugin calls `session.promptAsync` on that session with a message starting with `[Scheduled task]`.
+- If the target session is busy, the run is deferred by one minute.
+- If the target session no longer exists, the task is disabled and the last error is recorded.
+- One-off tasks are disabled after they fire.
+- Task state, run counters, and the last error persist across restarts.
+- Tasks only fire while at least one OpenCode process is running.
+
+## Storage
+
+Default location:
+
+```
+~/.local/share/opencode/scheduled-tasks/tasks.json
+```
+
+On Windows:
+
+```
+C:\Users\<you>\.local\share\opencode\scheduled-tasks\tasks.json
+```
+
+`leader.json` in the same directory is a short-lived lease used to avoid duplicate firing across OpenCode instances.
+
+## Configuration
+
+| Environment variable | Default | Purpose |
+|---|---|---|
+| `OPENCODE_SCHEDULER_DIR` | `~/.local/share/opencode/scheduled-tasks` | Store directory |
+| `OPENCODE_SCHEDULER_LOCALE` | System locale | `zh` or `en`; controls tool messages and injected instructions |
+| `OPENCODE_SCHEDULER_TICK_MS` | `15000` | Scheduler tick interval in milliseconds |
+
+## Security
+
+A scheduled task runs the instruction you asked for, with the permissions of the session that created it. Only create tasks whose instructions you trust, and review the task text when it is created.
+
+## Development
+
+Requires Node.js 20 or newer.
+
+```bash
+npm install
+npm test
+npm run check
+```
+
+The test suite uses a temporary store directory and a fast scheduler tick. It covers cron/daily parsing, task creation and management, manual runs, and the scheduler firing path.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,134 @@
+# opencode-natural-scheduler
+
+给 [OpenCode](https://opencode.ai) 用的自然语言定时任务插件。你只要说清楚"做什么、多久一次"，插件就会创建任务，并在到点时把任务指令注入回创建任务的那个会话。
+
+```
+你：每 20 分钟检查一次发票模块的错误日志，有异常就分析根因
+Agent：（调用 schedule_create）已创建定时任务 task-...，下次运行 2026-11-01 12:30
+```
+
+## 和其他调度插件的区别
+
+| | opencode-natural-scheduler | opencode-scheduler | opencode-cron |
+|---|---|---|---|
+| 自然语言创建任务 | 支持 | cron 配置 | cron 配置 |
+| OpenCode 关闭后仍运行 | 不支持 | 支持（launchd/systemd） | 不支持 |
+| 跨平台 | 支持 | macOS/Linux | 支持 |
+| 注入回原会话 | 支持 | 由任务定义 | 支持 |
+| 需要系统级守护进程 | 不需要 | 需要 | 不需要 |
+
+这个插件刻意做成进程内调度，不碰 launchd、systemd 或 Windows 服务。适合"OpenCode 开着时，按对话创建任务"的场景。
+
+## 安装
+
+在 OpenCode 配置里加入：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-natural-scheduler"]
+}
+```
+
+或者：
+
+```bash
+opencode plugin opencode-natural-scheduler
+```
+
+安装后重启 OpenCode。多个 OpenCode 进程会通过 `leader.json` 选出唯一调度者，避免同一个任务被重复触发。
+
+## 使用
+
+直接描述任务和时间：
+
+- `每 20 分钟检查一次发票模块的错误日志并汇报异常。`
+- `每天 09:00 汇总昨天失败的作业。`
+- `30 分钟后提醒我 review 部署。`
+- `工作日 18:00 收集当天指标。`
+
+模型会调用 `schedule_create`，并告诉你任务 id 和下次运行时间。
+
+管理任务也用自然语言：
+
+- `列出我的定时任务。`
+- `暂停 task-abc123。`
+- `把 task-abc123 改成每小时一次。`
+- `立即执行 task-abc123。`
+- `删除 task-abc123。`
+
+## 支持的频率
+
+| 类型 | 工具参数 | 示例 |
+|---|---|---|
+| 固定间隔 | `every_minutes` | `every_minutes: 20` |
+| 每天 | `daily_at` | `daily_at: "09:30"` |
+| Cron | `cron` | `cron: "0 9 * * 1-5"` |
+| 一次性 | `once_at` 或 `once_in_minutes` | `once_in_minutes: 30` |
+
+Cron 为 5 字段（分 时 日 月 周），使用本机时区。日和周同时受限时，任一匹配即可，符合标准 cron 语义。
+
+## 工具
+
+插件注册五个工具：
+
+- `schedule_create`
+- `schedule_list`
+- `schedule_update`
+- `schedule_delete`
+- `schedule_run_now`
+
+默认作用于当前会话；传 `session_id` 可指定其他会话，`all: true` 可列出全部任务。
+
+## 行为细节
+
+- 任务绑定创建它的会话。触发时调用 `session.promptAsync`，注入以 `[定时任务触发]` 开头的消息。
+- 目标会话正忙时，延后 1 分钟重试。
+- 目标会话已删除时，任务自动停用并记录错误。
+- 一次性任务执行后自动停用。
+- 任务状态、运行次数、最近错误都会持久化。
+- 至少有一个 OpenCode 进程在运行时，任务才会触发。
+
+## 存储位置
+
+默认：
+
+```
+~/.local/share/opencode/scheduled-tasks/tasks.json
+```
+
+Windows：
+
+```
+C:\Users\<你>\.local\share\opencode\scheduled-tasks\tasks.json
+```
+
+同目录下的 `leader.json` 是短期租约，用于多实例互斥。
+
+## 环境变量
+
+| 变量 | 默认值 | 作用 |
+|---|---|---|
+| `OPENCODE_SCHEDULER_DIR` | `~/.local/share/opencode/scheduled-tasks` | 数据目录 |
+| `OPENCODE_SCHEDULER_LOCALE` | 系统语言 | `zh` 或 `en`，控制工具消息和注入指令 |
+| `OPENCODE_SCHEDULER_TICK_MS` | `15000` | 调度轮询间隔（毫秒） |
+
+## 安全
+
+定时任务会按创建它的会话权限执行你写下的指令。只创建你信任的任务，并在创建时确认任务内容。
+
+## 开发
+
+需要 Node.js 20 或更新版本。
+
+```bash
+npm install
+npm test
+npm run check
+```
+
+测试使用临时数据目录和更快的调度间隔，覆盖 cron/每日解析、任务创建与管理、立即执行、以及调度触发链路。
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "opencode-natural-scheduler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Natural-language scheduled tasks for OpenCode: create recurring or one-off tasks by asking, with prompts injected back into the originating session.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "scheduler",
+    "scheduled-tasks",
+    "cron",
+    "automation",
+    "natural-language"
+  ],
+  "author": "lrj01232",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lrj01232/opencode-natural-scheduler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lrj01232/opencode-natural-scheduler/issues"
+  },
+  "homepage": "https://github.com/lrj01232/opencode-natural-scheduler#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.31"
+  },
+  "scripts": {
+    "test": "node --test test",
+    "check": "node --check src/core.js && node --check src/index.js",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core.js

@@ -0,0 +1,686 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+const SERVICE = "natural-scheduler"
+const DEFAULT_TICK_MS = 15_000
+const TICK_MS = readPositiveInt(process.env.OPENCODE_SCHEDULER_TICK_MS, DEFAULT_TICK_MS)
+const LEASE_MS = Math.max(90_000, TICK_MS * 3)
+const RETRY_MS = 60_000
+const INSTANCE_ID = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+const LOCALE = (process.env.OPENCODE_SCHEDULER_LOCALE
+  || new Intl.DateTimeFormat().resolvedOptions().locale
+  || "en").toLowerCase()
+const ZH = LOCALE.startsWith("zh")
+
+function t(zh, en) {
+  return ZH ? zh : en
+}
+
+function readPositiveInt(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback
+}
+
+export const INSTRUCTIONS = ZH
+  ? `## 定时任务
+本环境已加载 natural-scheduler 插件，提供 schedule_create / schedule_list / schedule_update / schedule_delete / schedule_run_now 工具。
+当用户提出"定时/每隔/每天/定期/到点/提醒我做…"等需求时，不要只回复计划，必须立即调用 schedule_create：从用户话中提取完整任务指令和频率；缺少关键信息时只问一个最短的问题。
+用户想查看、暂停、修改或删除任务时，使用 schedule_list / schedule_update / schedule_delete。
+定时任务触发时，消息以 "[定时任务触发]" 开头；直接执行其中的任务，不要再次创建定时任务，也不要询问是否继续。`
+  : `## Scheduled tasks
+The natural-scheduler plugin is enabled and provides schedule_create / schedule_list / schedule_update / schedule_delete / schedule_run_now.
+When the user asks for a recurring or timed action ("every 20 minutes", "daily at 9", "remind me", "run this later"), do not just describe a plan: immediately call schedule_create, extracting a self-contained task instruction and the schedule. Ask at most one short clarifying question if the frequency or task content is missing.
+Use schedule_list / schedule_update / schedule_delete when the user wants to inspect, pause, modify, or remove tasks.
+When a scheduled task fires, the message starts with "[Scheduled task]"; execute it directly, do not create another scheduled task, and do not ask for confirmation.`
+
+function pad(value) {
+  return String(value).padStart(2, "0")
+}
+
+export function localStamp(ts) {
+  const date = new Date(ts)
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+function asInt(value, name, min = 1, max = Number.MAX_SAFE_INTEGER) {
+  const number = Number(value)
+  if (!Number.isInteger(number) || number < min || number > max) {
+    throw new Error(t(
+      `${name} 必须是 ${min}-${max} 之间的整数`,
+      `${name} must be an integer between ${min} and ${max}`,
+    ))
+  }
+  return number
+}
+
+function parseCronField(text, min, max, name) {
+  const values = new Set()
+  for (const chunk of String(text).split(",")) {
+    if (!chunk) throw new Error(t(`cron ${name} 字段为空`, `cron ${name} field is empty`))
+    const pieces = chunk.split("/")
+    if (pieces.length > 2) {
+      throw new Error(t(`cron ${name} 字段无效: ${chunk}`, `invalid cron ${name} field: ${chunk}`))
+    }
+    const rangePart = pieces[0]
+    const step = pieces[1] === undefined ? 1 : asInt(pieces[1], t(`${name} 步长`, `${name} step`))
+    let lo
+    let hi
+    if (rangePart === "*") {
+      lo = min
+      hi = max
+    } else if (rangePart.includes("-")) {
+      const bounds = rangePart.split("-")
+      if (bounds.length !== 2) {
+        throw new Error(t(`cron ${name} 范围无效: ${rangePart}`, `invalid cron ${name} range: ${rangePart}`))
+      }
+      lo = asInt(bounds[0], name, min, max)
+      hi = asInt(bounds[1], name, min, max)
+      if (lo > hi) {
+        throw new Error(t(`cron ${name} 范围颠倒: ${rangePart}`, `cron ${name} range is reversed: ${rangePart}`))
+      }
+    } else {
+      lo = asInt(rangePart, name, min, max)
+      hi = pieces[1] === undefined ? lo : max
+    }
+    for (let value = lo; value <= hi; value += step) values.add(value)
+  }
+  if (values.size === 0) {
+    throw new Error(t(`cron ${name} 字段没有匹配值`, `cron ${name} field matches no values`))
+  }
+  return { values, wildcard: String(text).trim() === "*" }
+}
+
+export function parseCron(expression) {
+  const parts = String(expression).trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new Error(t("cron 必须是 5 个字段：分 时 日 月 周", "cron must have 5 fields: minute hour day month weekday"))
+  }
+  return {
+    minute: parseCronField(parts[0], 0, 59, t("分钟", "minute")),
+    hour: parseCronField(parts[1], 0, 23, t("小时", "hour")),
+    day: parseCronField(parts[2], 1, 31, t("日", "day")),
+    month: parseCronField(parts[3], 1, 12, t("月", "month")),
+    weekday: parseCronField(parts[4], 0, 7, t("周", "weekday")),
+  }
+}
+
+export function cronMatches(cron, date) {
+  if (!cron.minute.values.has(date.getMinutes())) return false
+  if (!cron.hour.values.has(date.getHours())) return false
+  if (!cron.month.values.has(date.getMonth() + 1)) return false
+  const dayOk = cron.day.values.has(date.getDate())
+  const weekday = date.getDay()
+  const weekdayOk = cron.weekday.values.has(weekday) || (weekday === 0 && cron.weekday.values.has(7))
+  if (!cron.day.wildcard && !cron.weekday.wildcard) return dayOk || weekdayOk
+  return dayOk && weekdayOk
+}
+
+export function nextCron(expression, from) {
+  const cron = parseCron(expression)
+  const start = new Date(from)
+  start.setSeconds(0, 0)
+  start.setMinutes(start.getMinutes() + 1)
+  const limit = from + 366 * 24 * 60 * 60 * 1000
+  for (let ts = start.getTime(); ts <= limit; ts += 60_000) {
+    if (cronMatches(cron, new Date(ts))) return ts
+  }
+  throw new Error(t("cron 在未来一年内没有匹配时间", "cron has no matching time within the next year"))
+}
+
+function normalizeDaily(text) {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(String(text).trim())
+  if (!match) {
+    throw new Error(t("daily_at 格式应为 HH:MM，例如 09:30", "daily_at must use HH:MM, for example 09:30"))
+  }
+  const hour = asInt(match[1], t("小时", "hour"), 0, 23)
+  const minute = asInt(match[2], t("分钟", "minute"), 0, 59)
+  return `${pad(hour)}:${pad(minute)}`
+}
+
+export function nextDaily(time, from) {
+  const [hour, minute] = time.split(":").map(Number)
+  const next = new Date(from)
+  next.setSeconds(0, 0)
+  next.setHours(hour, minute, 0, 0)
+  if (next.getTime() <= from) next.setDate(next.getDate() + 1)
+  return next.getTime()
+}
+
+function hasScheduleArgs(args) {
+  return [
+    args.every_minutes,
+    args.daily_at,
+    args.cron,
+    args.once_at,
+    args.once_in_minutes,
+  ].some((value) => value !== undefined && value !== null && value !== "")
+}
+
+export function parseScheduleArgs(args) {
+  const given = [
+    ["every_minutes", args.every_minutes],
+    ["daily_at", args.daily_at],
+    ["cron", args.cron],
+    ["once_at", args.once_at],
+    ["once_in_minutes", args.once_in_minutes],
+  ].filter(([, value]) => value !== undefined && value !== null && value !== "")
+
+  if (given.length !== 1) {
+    throw new Error(t(
+      "必须且只能指定一种频率：every_minutes / daily_at / cron / once_at / once_in_minutes",
+      "specify exactly one schedule: every_minutes / daily_at / cron / once_at / once_in_minutes",
+    ))
+  }
+
+  const [key, value] = given[0]
+  if (key === "every_minutes") return { type: "interval", minutes: asInt(value, "every_minutes") }
+  if (key === "daily_at") return { type: "daily", time: normalizeDaily(value) }
+  if (key === "cron") {
+    parseCron(value)
+    return { type: "cron", expression: String(value).trim() }
+  }
+  if (key === "once_in_minutes") {
+    return { type: "once", at: Date.now() + asInt(value, "once_in_minutes") * 60_000 }
+  }
+  const at = Date.parse(String(value))
+  if (!Number.isFinite(at)) {
+    throw new Error(t(
+      "once_at 无法解析，请使用 ISO 时间，例如 2026-11-01T09:00:00+08:00",
+      "once_at is not parseable; use an ISO timestamp such as 2026-11-01T09:00:00+08:00",
+    ))
+  }
+  if (at <= Date.now()) throw new Error(t("once_at 必须晚于当前时间", "once_at must be in the future"))
+  return { type: "once", at }
+}
+
+export function computeNext(schedule, from) {
+  if (schedule.type === "interval") return from + schedule.minutes * 60_000
+  if (schedule.type === "daily") return nextDaily(schedule.time, from)
+  if (schedule.type === "cron") return nextCron(schedule.expression, from)
+  if (schedule.type === "once") return schedule.at
+  throw new Error(t(`未知频率类型: ${schedule.type}`, `unknown schedule type: ${schedule.type}`))
+}
+
+export function nextAfterRun(task, now) {
+  const schedule = task.schedule
+  if (schedule.type === "once") return null
+  if (schedule.type === "interval") {
+    let next = computeNext(schedule, task.nextRunAt)
+    while (next <= now) next += schedule.minutes * 60_000
+    return next
+  }
+  return computeNext(schedule, Math.max(now, task.nextRunAt))
+}
+
+export function scheduleLabel(schedule) {
+  if (schedule.type === "interval") return t(`每 ${schedule.minutes} 分钟`, `every ${schedule.minutes} min`)
+  if (schedule.type === "daily") return t(`每天 ${schedule.time}`, `daily at ${schedule.time}`)
+  if (schedule.type === "cron") return `cron ${schedule.expression}`
+  if (schedule.type === "once") return t(`单次 ${localStamp(schedule.at)}`, `once at ${localStamp(schedule.at)}`)
+  return t("未知", "unknown")
+}
+
+function storeDir() {
+  return process.env.OPENCODE_SCHEDULER_DIR
+    || process.env.OPENCODE_SCHEDULE_DIR
+    || path.join(os.homedir(), ".local", "share", "opencode", "scheduled-tasks")
+}
+
+function tasksFile() {
+  return path.join(storeDir(), "tasks.json")
+}
+
+function lockFile() {
+  return path.join(storeDir(), "leader.json")
+}
+
+function ensureDir() {
+  fs.mkdirSync(storeDir(), { recursive: true })
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"))
+  } catch {
+    return fallback
+  }
+}
+
+function writeJson(file, value) {
+  ensureDir()
+  const tmp = `${file}.${INSTANCE_ID}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2))
+  fs.renameSync(tmp, file)
+}
+
+export function readStore(file = tasksFile()) {
+  const value = readJson(file, null)
+  if (value && Array.isArray(value.tasks)) return value
+  return { version: 1, tasks: [] }
+}
+
+export function writeStore(store, file = tasksFile()) {
+  writeJson(file, store)
+}
+
+function pushRun(task, entry) {
+  if (!Array.isArray(task.runs)) task.runs = []
+  task.runs.push(entry)
+  if (task.runs.length > 50) task.runs = task.runs.slice(-50)
+}
+
+function taskLine(task) {
+  const state = task.enabled
+    ? t("开启", "enabled")
+    : task.done
+      ? t("已完成", "done")
+      : t("已暂停", "paused")
+  const next = task.nextRunAt ? localStamp(task.nextRunAt) : "-"
+  const last = task.lastRunAt ? localStamp(task.lastRunAt) : "-"
+  const status = task.lastStatus ? ` | ${t("上次状态", "last status")} ${task.lastStatus}` : ""
+  return `- ${task.id} | ${task.name} | ${state} | ${scheduleLabel(task.schedule)} | ${t("下次", "next")} ${next} | ${t("上次", "last")} ${last}${status}`
+}
+
+async function sessionBusy(client, sessionID) {
+  try {
+    const result = await client.session.status({})
+    const map = result?.data ?? result
+    const status = map?.[sessionID]
+    return status?.type === "busy" || status?.type === "retry"
+  } catch {
+    return false
+  }
+}
+
+function renderPrompt(task) {
+  return t(
+    `[定时任务触发] ${task.name}（${localStamp(Date.now())}）
+
+${task.prompt}
+
+（这是 natural-scheduler 插件自动注入的消息：请直接执行上面的任务，不要为此再次创建定时任务，也不要询问是否继续。完成后简要汇报结果。）`,
+    `[Scheduled task] ${task.name} (${localStamp(Date.now())})
+
+${task.prompt}
+
+(This message was injected automatically by the natural-scheduler plugin. Execute the task directly; do not create another scheduled task and do not ask for confirmation. Report the result briefly.)`,
+  )
+}
+
+function findTask(store, id) {
+  const task = store.tasks.find((item) => item.id === id)
+  if (!task) throw new Error(t(`找不到定时任务: ${id}`, `scheduled task not found: ${id}`))
+  return task
+}
+
+function createTask(args, sessionID) {
+  const name = String(args.name ?? "").trim()
+  const prompt = String(args.prompt ?? "").trim()
+  if (!name) throw new Error(t("name 不能为空", "name must not be empty"))
+  if (!prompt) throw new Error(t("prompt 不能为空", "prompt must not be empty"))
+  const schedule = parseScheduleArgs(args)
+  const now = Date.now()
+  const task = {
+    id: `task-${now.toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+    name,
+    prompt,
+    schedule,
+    sessionID: String(args.session_id || sessionID),
+    ...(args.agent ? { agent: String(args.agent) } : {}),
+    enabled: true,
+    done: false,
+    createdAt: now,
+    updatedAt: now,
+    lastRunAt: null,
+    lastStatus: null,
+    lastError: null,
+    runCount: 0,
+    nextRunAt: computeNext(schedule, now),
+    runs: [],
+  }
+  const store = readStore()
+  store.tasks.push(task)
+  writeStore(store)
+  return task
+}
+
+export function createTools(tool, client) {
+  const scheduleCreate = tool({
+    description: t(
+      "创建一个定时任务：到点后在目标会话自动注入任务指令并执行。支持每隔 N 分钟、每天 HH:MM、5 字段 cron、一次性指定时间。",
+      "Create a scheduled task that injects a prompt into a target session when it fires. Supports intervals, daily times, 5-field cron, and one-off timestamps.",
+    ),
+    args: {
+      name: tool.schema.string().describe(t("任务名称，简短", "Short task name")),
+      prompt: tool.schema.string().describe(t(
+        "到点后要执行的完整任务指令，需自包含",
+        "Self-contained instruction to execute when the task fires",
+      )),
+      every_minutes: tool.schema.number().int().min(1).optional().describe(t("每隔多少分钟执行一次", "Run every N minutes")),
+      daily_at: tool.schema.string().regex(/^\d{1,2}:\d{2}$/).optional().describe(t("每天本地时间 HH:MM", "Run daily at local time HH:MM")),
+      cron: tool.schema.string().optional().describe(t("5 字段 cron：分 时 日 月 周", "5-field cron: minute hour day month weekday")),
+      once_at: tool.schema.string().optional().describe(t("一次性时间，ISO 8601", "One-off ISO 8601 timestamp")),
+      once_in_minutes: tool.schema.number().int().min(1).optional().describe(t("N 分钟后执行一次", "Run once after N minutes")),
+      agent: tool.schema.string().optional().describe(t("可选：执行时使用的 agent", "Optional agent name to run with")),
+      session_id: tool.schema.string().optional().describe(t("可选：目标任务会话，默认当前会话", "Optional target session; defaults to the current session")),
+    },
+    async execute(args, context) {
+      const task = createTask(args, context.sessionID)
+      return [
+        t("定时任务已创建", "Scheduled task created"),
+        `id: ${task.id}`,
+        `${t("名称", "name")}: ${task.name}`,
+        `${t("频率", "schedule")}: ${scheduleLabel(task.schedule)}`,
+        `${t("下次运行", "next run")}: ${localStamp(task.nextRunAt)}`,
+        `${t("目标会话", "target session")}: ${task.sessionID}`,
+        task.agent ? `agent: ${task.agent}` : null,
+      ].filter(Boolean).join("\n")
+    },
+  })
+
+  const scheduleList = tool({
+    description: t(
+      "列出定时任务及其状态、频率、下次运行时间。默认只列当前会话，all=true 列全部。",
+      "List scheduled tasks with state, schedule, and next run time. Defaults to the current session; pass all=true for every session.",
+    ),
+    args: {
+      all: tool.schema.boolean().optional().describe(t("是否列出所有会话的任务", "List tasks from every session")),
+      session_id: tool.schema.string().optional().describe(t("指定会话 id", "Session id to filter by")),
+    },
+    async execute(args, context) {
+      const store = readStore()
+      const sessionID = args.session_id || context.sessionID
+      const tasks = args.all ? store.tasks : store.tasks.filter((task) => task.sessionID === sessionID)
+      if (tasks.length === 0) return t("没有定时任务。", "No scheduled tasks.")
+      const sorted = [...tasks].sort((a, b) => (a.nextRunAt ?? Infinity) - (b.nextRunAt ?? Infinity))
+      return [
+        t(`定时任务（${args.all ? "全部" : "本会话"} ${tasks.length} 个）`, `Scheduled tasks (${args.all ? "all" : "this session"}: ${tasks.length})`),
+        ...sorted.map(taskLine),
+      ].join("\n")
+    },
+  })
+
+  const scheduleUpdate = tool({
+    description: t(
+      "修改定时任务：名称、指令、启停、执行 agent、目标会话或频率。",
+      "Update a scheduled task: name, prompt, enabled state, agent, target session, or schedule.",
+    ),
+    args: {
+      id: tool.schema.string().describe(t("任务 id", "Task id")),
+      name: tool.schema.string().optional(),
+      prompt: tool.schema.string().optional(),
+      agent: tool.schema.string().optional(),
+      session_id: tool.schema.string().optional(),
+      enabled: tool.schema.boolean().optional(),
+      every_minutes: tool.schema.number().int().min(1).optional(),
+      daily_at: tool.schema.string().regex(/^\d{1,2}:\d{2}$/).optional(),
+      cron: tool.schema.string().optional(),
+      once_at: tool.schema.string().optional(),
+      once_in_minutes: tool.schema.number().int().min(1).optional(),
+    },
+    async execute(args) {
+      const store = readStore()
+      const task = findTask(store, args.id)
+      const now = Date.now()
+      if (args.name !== undefined) {
+        const name = String(args.name).trim()
+        if (!name) throw new Error(t("name 不能为空", "name must not be empty"))
+        task.name = name
+      }
+      if (args.prompt !== undefined) {
+        const prompt = String(args.prompt).trim()
+        if (!prompt) throw new Error(t("prompt 不能为空", "prompt must not be empty"))
+        task.prompt = prompt
+      }
+      if (args.agent !== undefined) {
+        if (args.agent) task.agent = String(args.agent)
+        else delete task.agent
+      }
+      if (args.session_id !== undefined) task.sessionID = String(args.session_id)
+      if (hasScheduleArgs(args)) {
+        task.schedule = parseScheduleArgs(args)
+        task.done = false
+        task.enabled = args.enabled ?? true
+        task.nextRunAt = task.enabled ? computeNext(task.schedule, now) : null
+      } else if (args.enabled !== undefined) {
+        task.enabled = args.enabled
+        if (args.enabled) {
+          if (!task.nextRunAt || task.done) {
+            if (task.schedule.type === "once" && task.schedule.at <= now) {
+              throw new Error(t(
+                "该单次任务已过期，请提供新的 once_at 或其他频率",
+                "this one-off task has expired; provide a new once_at or another schedule",
+              ))
+            }
+            task.nextRunAt = computeNext(task.schedule, now)
+            task.done = false
+          }
+        } else {
+          task.nextRunAt = null
+        }
+      }
+      task.updatedAt = now
+      writeStore(store)
+      return [
+        t("定时任务已更新", "Scheduled task updated"),
+        `id: ${task.id}`,
+        `${t("名称", "name")}: ${task.name}`,
+        `${t("状态", "state")}: ${task.enabled ? t("开启", "enabled") : t("暂停", "paused")}`,
+        `${t("频率", "schedule")}: ${scheduleLabel(task.schedule)}`,
+        `${t("下次运行", "next run")}: ${task.nextRunAt ? localStamp(task.nextRunAt) : "-"}`,
+        `${t("目标会话", "target session")}: ${task.sessionID}`,
+      ].join("\n")
+    },
+  })
+
+  const scheduleDelete = tool({
+    description: t("删除定时任务。", "Delete a scheduled task."),
+    args: {
+      id: tool.schema.string().describe(t("任务 id", "Task id")),
+    },
+    async execute(args) {
+      const store = readStore()
+      const task = findTask(store, args.id)
+      store.tasks = store.tasks.filter((item) => item.id !== task.id)
+      writeStore(store)
+      return t(`已删除定时任务: ${task.id} (${task.name})`, `Deleted scheduled task: ${task.id} (${task.name})`)
+    },
+  })
+
+  const scheduleRunNow = tool({
+    description: t("立即执行一次定时任务，不改变原有计划。", "Run a scheduled task immediately without changing its schedule."),
+    args: {
+      id: tool.schema.string().describe(t("任务 id", "Task id")),
+    },
+    async execute(args) {
+      const store = readStore()
+      const task = findTask(store, args.id)
+      if (await sessionBusy(client, task.sessionID)) {
+        return t(`任务 ${task.id} 的目标会话正忙，请稍后再试。`, `Target session for ${task.id} is busy; try again later.`)
+      }
+      const result = await client.session.promptAsync({
+        path: { id: task.sessionID },
+        body: {
+          ...(task.agent ? { agent: task.agent } : {}),
+          parts: [{ type: "text", text: renderPrompt(task) }],
+        },
+      })
+      if (result?.error) {
+        const detail = result.error?.data?.message || result.error?.message || JSON.stringify(result.error)
+        throw new Error(detail)
+      }
+      const now = Date.now()
+      task.lastRunAt = now
+      task.lastStatus = "fired"
+      task.lastError = null
+      task.runCount = (task.runCount ?? 0) + 1
+      task.updatedAt = now
+      pushRun(task, { at: now, status: "fired", detail: "manual run" })
+      writeStore(store)
+      return t(`已立即执行定时任务: ${task.id} (${task.name})`, `Ran scheduled task now: ${task.id} (${task.name})`)
+    },
+  })
+
+  return {
+    schedule_create: scheduleCreate,
+    schedule_list: scheduleList,
+    schedule_update: scheduleUpdate,
+    schedule_delete: scheduleDelete,
+    schedule_run_now: scheduleRunNow,
+  }
+}
+
+export function createScheduler(client) {
+  let timer = null
+  let leader = false
+  let stopped = false
+  let ticking = false
+
+  const log = async (level, message, extra) => {
+    try {
+      await client.app.log({ body: { service: SERVICE, level, message, extra } })
+    } catch {
+    }
+  }
+
+  const readLock = () => readJson(lockFile(), null)
+
+  const pidAlive = (pid) => {
+    if (!pid) return false
+    try {
+      process.kill(pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  const claim = () => {
+    try {
+      const lock = readLock()
+      const fresh = lock && lock.instanceId !== INSTANCE_ID
+        && Date.now() - Number(lock.ts ?? 0) < LEASE_MS
+        && pidAlive(Number(lock.pid))
+      if (fresh) return false
+      writeJson(lockFile(), { instanceId: INSTANCE_ID, pid: process.pid, ts: Date.now() })
+      const check = readLock()
+      return check?.instanceId === INSTANCE_ID
+    } catch (error) {
+      void log("warn", `leader claim failed: ${String(error?.message ?? error)}`)
+      return false
+    }
+  }
+
+  const heartbeat = () => {
+    try {
+      writeJson(lockFile(), { instanceId: INSTANCE_ID, pid: process.pid, ts: Date.now() })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  const fire = async (sessionID, task) => {
+    const result = await client.session.promptAsync({
+      path: { id: sessionID },
+      body: {
+        ...(task.agent ? { agent: task.agent } : {}),
+        parts: [{ type: "text", text: renderPrompt(task) }],
+      },
+    })
+    if (result?.error) {
+      const detail = result.error?.data?.message || result.error?.message || JSON.stringify(result.error)
+      throw new Error(detail)
+    }
+  }
+
+  const tick = async () => {
+    if (stopped || ticking) return
+    ticking = true
+    try {
+      if (!leader) leader = claim()
+      if (!leader) return
+      heartbeat()
+
+      const now = Date.now()
+      const dueIds = readStore().tasks
+        .filter((task) => task.enabled && task.nextRunAt && task.nextRunAt <= now)
+        .map((task) => task.id)
+
+      for (const id of dueIds) {
+        const store = readStore()
+        const task = store.tasks.find((item) => item.id === id)
+        if (!task || !task.enabled || !task.nextRunAt || task.nextRunAt > Date.now()) continue
+
+        const dueAt = task.nextRunAt
+        if (await sessionBusy(client, task.sessionID)) {
+          task.nextRunAt = Date.now() + RETRY_MS
+          task.lastStatus = "deferred"
+          task.updatedAt = Date.now()
+          pushRun(task, { at: Date.now(), status: "deferred", detail: "session busy" })
+          writeStore(store)
+          continue
+        }
+
+        try {
+          await fire(task.sessionID, task)
+          task.lastRunAt = Date.now()
+          task.lastStatus = "fired"
+          task.lastError = null
+          task.runCount = (task.runCount ?? 0) + 1
+          task.updatedAt = Date.now()
+          pushRun(task, { at: task.lastRunAt, status: "fired" })
+          if (task.schedule.type === "once") {
+            task.enabled = false
+            task.done = true
+            task.nextRunAt = null
+          } else {
+            task.nextRunAt = nextAfterRun({ ...task, nextRunAt: dueAt }, Date.now())
+          }
+        } catch (error) {
+          const message = String(error?.message ?? error)
+          task.lastStatus = "error"
+          task.lastError = message
+          task.updatedAt = Date.now()
+          pushRun(task, { at: Date.now(), status: "error", detail: message })
+          if (/404|not found|不存在/i.test(message)) {
+            task.enabled = false
+            task.nextRunAt = null
+          } else {
+            task.nextRunAt = Date.now() + RETRY_MS
+          }
+        }
+        writeStore(store)
+      }
+    } catch (error) {
+      void log("error", `scheduler tick failed: ${String(error?.message ?? error)}`)
+    } finally {
+      ticking = false
+    }
+  }
+
+  const start = () => {
+    ensureDir()
+    leader = claim()
+    timer = setInterval(() => { void tick() }, TICK_MS)
+    if (timer && typeof timer.unref === "function") timer.unref()
+    void tick()
+    void log("info", leader ? "scheduler started as leader" : "scheduler started as follower")
+  }
+
+  const stop = async () => {
+    stopped = true
+    if (timer) clearInterval(timer)
+    if (leader) {
+      try {
+        const lock = readLock()
+        if (lock?.instanceId === INSTANCE_ID) fs.unlinkSync(lockFile())
+      } catch {
+      }
+    }
+    await log("info", "scheduler stopped")
+  }
+
+  return { start, stop }
+}

package/src/index.js

@@ -0,0 +1,15 @@
+import { tool } from "@opencode-ai/plugin"
+import { INSTRUCTIONS, createScheduler, createTools } from "./core.js"
+
+export const NaturalScheduler = async ({ client }) => {
+  const scheduler = createScheduler(client)
+  scheduler.start()
+  return {
+    dispose: scheduler.stop,
+    "experimental.chat.system.transform": async (_input, output) => {
+      if (!Array.isArray(output.system)) output.system = []
+      output.system.push(INSTRUCTIONS)
+    },
+    tool: createTools(tool, client),
+  }
+}