opencode-supertask 0.1.19 → 0.1.21

package/README.md

@@ -7,6 +7,8 @@ AI-powered task queue for [OpenCode](https://opencode.ai) agents — schedule, r
 
 [简体中文](#简体中文)
 
+Documentation: [current architecture](docs/architecture.md) · [operations and troubleshooting](docs/operations.md) · [document index](docs/README.md)
+
 ## Installation
 
 ### Quick Install
@@ -19,12 +21,14 @@ Add the plugin to `~/.config/opencode/opencode.json`:
 }
 ```
 
-Restart OpenCode. That's it.
+Restart OpenCode to load 11 `supertask_*` tools. Then choose how to run the Gateway:
+
+```bash
+supertask install   # recommended for long-running use: explicit pm2 setup
+supertask gateway   # foreground mode: no pm2 required
+```
 
-The plugin auto-starts a Gateway process (via pm2) and injects:
-- 10 MCP tools (`supertask_add`, `supertask_next`, `supertask_start`, `supertask_done`, `supertask_fail`, `supertask_get`, `supertask_list`, `supertask_status`, `supertask_retry`, `supertask_schedule`)
-- A `supertask-runner` agent (used internally by the Gateway)
-- A Web Dashboard at http://localhost:4680
+The plugin never installs global dependencies by itself. Without a running Gateway, queue-management tools still work, but scheduled and queued tasks are not executed and the Dashboard is unavailable.
 
 ### Uninstall
 
@@ -41,7 +45,7 @@ rm ~/.local/share/opencode/tasks.db
 ### CLI Install / Uninstall
 
 ```bash
-supertask install     # Install Gateway as pm2 service (auto-start, crash recovery)
+supertask install     # Explicitly install/configure pm2 and start Gateway
 supertask uninstall   # Stop and remove Gateway from pm2
 ```
 
@@ -64,7 +68,7 @@ Then add the local path to your config:
 
 ## Quick Start
 
-After installation, the Gateway starts automatically. Use the MCP tools in OpenCode:
+After starting the Gateway with `supertask install` or `supertask gateway`, use the MCP tools in OpenCode:
 
 ```
 Create a task: "帮我生成项目的 README" with agent "explore"
@@ -87,7 +91,8 @@ supertask ui                           # open Web Dashboard in browser
 supertask config                       # show current config
 
 # Task management
-supertask add -n "Task" -a "agent" -p "prompt" --importance 5
+supertask add -n "Task" -a "agent" -p "prompt" --importance 5 \
+  --max-retries 3 --retry-backoff "30s" --timeout "30min"
 supertask list [--status pending] [--limit 20]
 supertask get --id 1
 supertask status
@@ -100,7 +105,8 @@ supertask template add --name "Daily" --agent "gen" \
 supertask template add --name "Delayed" --agent "gen" \
   --prompt "..." --type delayed --delay "30min"
 supertask template add --name "Hourly" --agent "gen" \
-  --prompt "..." --type recurring --interval "1h"
+  --prompt "..." --type recurring --interval "1h" \
+  --batch "reports" --retry-backoff "30s" --timeout "30min"
 supertask template list
 supertask template enable --id 1
 ```
@@ -121,8 +127,8 @@ Schedule supports friendly duration strings:
 ## Architecture
 
 ```
-Gateway (auto-started by pm2)
-├── Worker     → claim tasks, spawn supertask-runner via opencode run
+Gateway (foreground or optionally managed by pm2)
+├── Worker     → claim tasks, execute the target agent via opencode run
 ├── Scheduler  → clone tasks from templates (cron / delayed / recurring)
 ├── Watchdog   → heartbeat timeout, auto-retry, data cleanup
 └── Dashboard  → Web UI on port 4680 (Hono SSR)
@@ -130,29 +136,42 @@ Gateway (auto-started by pm2)
 
 Config file: `~/.config/opencode/supertask.json`
 
+The complete configuration reference and restart semantics are documented in [Operations and Troubleshooting](docs/operations.md).
+
 ```json
 {
-  "worker": { "maxConcurrency": 2 },
-  "scheduler": { "enabled": true, "catchUp": "next" },
-  "watchdog": { "heartbeatTimeoutMs": 600000, "retentionDays": 30 },
+  "configVersion": 2,
+  "worker": { "maxConcurrency": 2, "taskTimeoutMs": 1800000, "shutdownGracePeriodMs": 30000 },
+  "scheduler": { "enabled": true, "checkIntervalMs": 1000 },
+  "watchdog": {
+    "heartbeatTimeoutMs": 600000,
+    "checkIntervalMs": 60000,
+    "cleanupIntervalMs": 86400000,
+    "retentionDays": 30
+  },
   "dashboard": { "enabled": true, "port": 4680 }
 }
 ```
 
 Key mechanisms:
-- **Auto-start** — Plugin auto-installs pm2 and starts Gateway on first use
-- **Auto-upgrade** — Plugin detects version changes and auto-reloads Gateway
+- **Process supervision** — optional pm2 crash recovery; plugin load never installs pm2, but can reuse an existing installation
+- **Version-aware restart** — if pm2 is already installed, plugin load starts or restarts the Gateway when the package version changes
 - **Process lock** — SQLite `BEGIN IMMEDIATE` ensures single instance
+- **Readiness check** — PM2 PID must match a fresh, ready Gateway lock; `/health` also checks component activity
 - **Heartbeat** — Worker updates every 30s; Watchdog kills stale processes
-- **Exponential backoff** — 30s × 2^n, capped at 30min
-- **Dead letter queue** — Exhausted retries → `dead_letter`, manually recoverable
+- **Graceful shutdown** — stop claiming work, drain active tasks for 30s, then interrupt and requeue only unfinished tasks
+- **Exponential backoff** — configurable base × 2^n, capped at 30min
+- **Dead letter queue** — `maxRetries` additional retries exhausted → `dead_letter`, manually recoverable
 - **Batch isolation** — Same `batchId` serial; different `batchId` parallel
-- **Priority** — `urgency DESC → importance DESC → createdAt ASC`
+- **Priority** — `urgency DESC → importance DESC → createdAt ASC → id ASC`
+- **Local Dashboard boundary** — loopback-only listener, same-origin write checks, escaped database output
 
 ## Web Dashboard
 
 http://localhost:4680 — 4 pages:
 
+Health endpoint: `GET http://localhost:4680/health` returns 200 only after Gateway startup completes and its internal loops remain active.
+
 | Page | Features |
 |------|----------|
 | Task Queue | Filter by status, retry, delete |
@@ -182,6 +201,8 @@ MIT
 
 SuperTask 是一个基于 SQLite 的 AI Agent 任务调度系统，专为 [OpenCode](https://opencode.ai) 设计。
 
+详细文档：[当前架构与决策](docs/architecture.md) · [运行与排障手册](docs/operations.md) · [文档索引](docs/README.md)
+
 ### 安装
 
 在 `~/.config/opencode/opencode.json` 中添加：
@@ -192,10 +213,14 @@ SuperTask 是一个基于 SQLite 的 AI Agent 任务调度系统，专为 [OpenC
 }
 ```
 
-重启 OpenCode 即可。插件会自动：
-- 安装 pm2 并启动 Gateway 常驻进程
-- 注入 10 个 MCP 工具和 supertask-runner Agent
-- 启动 Web 控制台（http://localhost:4680）
+重启 OpenCode 后会注入 11 个 `supertask_*` 工具。随后选择一种 Gateway 运行方式：
+
+```bash
+supertask install   # 长期运行推荐：显式安装/配置 pm2 并启动 Gateway
+supertask gateway   # 前台运行：不需要 pm2
+```
+
+插件不会自行安装全局依赖。Gateway 未运行时仍可管理队列，但不会执行排队/定时任务，也不会启动 Web 控制台。
 
 ### 卸载
 
@@ -223,8 +248,9 @@ supertask template add --type cron --cron "0 9 * * *" ...
 ### 核心功能
 
 - **任务队列** — 优先级调度、批次隔离、依赖管理
-- **自动启动** — 插件首次加载时自动安装 pm2 并启动 Gateway
-- **自动升级** — 插件更新后自动检测版本变化并 reload Gateway
+- **安全停止** — 默认等待在途任务 30 秒；超时任务才会被中断并重新排队
+- **进程守护** — 可选 pm2 崩溃恢复；插件加载不会安装 pm2，但可复用机器上已有的 PM2
+- **版本感知重启** — 已安装 pm2 时，插件加载会在包版本变化后启动或重启 Gateway
 - **定时任务** — cron / delayed / recurring，支持友好时间格式
 - **Web 控制台** — 任务监控、执行日志、在线配置、清空数据库
 - **Session 追踪** — 自动从 opencode run 输出中捕获 session ID