pi-cc-loop 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lei Fu (tarnish233)
+
+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,126 @@
-# Temporary Holding Version
+# pi-cc-loop
 
-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.
+> 在 Pi 里复刻 Claude Code 的 `/loop`：固定间隔 cron、自选间隔、兜底心跳和可选状态条。
+
+## 快速开始
+
+```bash
+# 本地开发：把仓库软链接到 Pi 扩展目录
+ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
+
+# 发布后
+pi install npm:pi-cc-loop
+```
+
+安装后执行 `/reload`。
+
+## 功能
+
+| 功能 | 说明 | 入口 |
+| --- | --- | --- |
+| 固定间隔 | 5 字段 cron；`30s`、`5m`、`2h`、`1d`；秒向上取整到分钟 | `/loop 5m <prompt>` |
+| 自选间隔 | 模型每轮用 `schedule_wakeup` 决定下次延迟（60–3600s） | `/loop <prompt>` |
+| 自然语言间隔 | 命令层认不出时交给模型解析（中英文均可） | `/loop 每30秒 ...` |
+| 立即执行 | 创建后马上跑一次，不等首个 cron | 自动 |
+| 漏跑合并 | agent 忙时到点只记一次 pending，空闲后发一条 | 自动 |
+| 兜底心跳 | 模型忘记调度时 arm 一次 20 分钟心跳，预算 1 次 | 自动 |
+| 次数上限 | `--max N`，到顶自动删除 | 标志 |
+| 持久化 | `--durable` 写入 `.pi/scheduled_tasks.json` | 标志 |
+| 状态条 | 输入框上方状态行，默认关闭 | `/loop widget on\|off` |
+
+## 命令
+
+```text
+/loop [间隔] <prompt>     按间隔重复跑
+/loop <prompt>            间隔交给模型判断
+/loop                     使用 .pi/loop.md 或内置维护 prompt
+/loop status              列出当前 loop
+/loop stop [id]           停止一个或全部
+/loop widget on|off       状态条
+/loop settings ...        界面设置
+/loop help                帮助
+```
+
+标志：`--durable` 写入 `.pi/scheduled_tasks.json`；`--max N` 触发 N 次后自动停止。
+
+间隔写法：
+
+- `30s`、`5m`、`2h`、`1d`
+- `check the deploy every 20m`
+- 不整除的间隔按 CC 规则取整并提示：`7m` → `*/6`，`30s` → 每分钟
+- 其他语言（如「每30秒」）交给模型解析
+
+## 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `cron_create` | 创建固定间隔任务；支持 `recurring`、`durable`、`maxFires` |
+| `cron_delete` | 按 id 取消 |
+| `cron_list` | 列出任务 |
+| `schedule_wakeup` | 自选间隔：安排下次唤醒，或 `stop: true` 结束 |
+
+`schedule_wakeup` 参数：
+
+- `delaySeconds`：60–3600，越界自动钳制
+- `reason`：一句原因
+- `prompt`：原样传回 `/loop` 的 prompt
+- `stop`：结束当前自选间隔 loop
+
+## 设置
+
+两个 pi-cc 扩展共享 `~/.pi/agent/pi-cc.json`：
+
+```jsonc
+{
+  "compactMessages": true,          // 两行 marker / 旧的带底色卡片
+  "compactToolRows": true,          // 一行工具结果 / Pi 默认工具行
+  "managePiCcExtensions": true      // 自动维护 pi-cc-extensions 的 excludeRenderers
+}
+```
+
+用命令切换：
+
+```text
+/loop settings
+/loop settings messages on|off
+/loop settings tools on|off
+```
+
+- 已画出的旧行需要 `/reload` 才会换样式
+- 环境变量覆盖：`PI_CC_COMPACT_MESSAGES=0`、`PI_CC_COMPACT_TOOL_ROWS=0`、`PI_CC_MANAGE_CCSTYLE=0`
+
+> 如果装了 `pi-cc-extensions`，`tools on` 会把本扩展的工具名加入它的 `excludeRenderers`；
+> `tools off` 只移除自己加过的名字。它只在启动时读配置，切换后需要 `/reload`。
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `PI_LOOP_MAX_AGE_DAYS` | `7` | 任务最长存活天数，`0` 不过期 |
+| `PI_LOOP_KEEPALIVE_SECONDS` | `1200` | 兜底心跳；`0` 禁用 |
+| `PI_LOOP_JITTER` | `0` | 抖动比例 0–1 |
+| `PI_LOOP_SCAN_MS` | `1000` | 调度扫描间隔 |
+
+## 兼容性
+
+- Node.js `>=22.19.0`
+- Pi `1.3.0`（开发环境）
+- 与 `pi-cc-extensions` 共存，见上面的设置说明
+
+## 本地开发
+
+```bash
+node --test tests/*.test.mjs
+npx --yes typescript@5.9.3 tsc --noEmit -p tsconfig.json
+```
+
+## 说明
+
+- 行为对齐 Claude Code v2.1.306 的 `/loop`，用 Pi 扩展 API 实现。
+- `/loop stop` 代替 CC 的 Esc；状态条默认关闭，和 CC 主会话一致。
+- `cron_create` 的 `maxFires` 是额外加固；CC 没有次数上限。
+- `/loop stop` 会连带停掉该 chain 绑定的 Monitor。
+
+## 许可证
+
+MIT

package/config.ts

@@ -0,0 +1,173 @@
+/**
+ * Shared settings for the pi-cc extensions.
+ *
+ * Both pi-cc-loop and pi-cc-monitor read the same small JSON file so a single
+ * toggle changes the look of both packages. The file is optional; when it is
+ * missing or malformed the defaults apply.
+ *
+ *   ~/.pi/agent/pi-cc.json
+ *   {
+ *     "compactMessages": true,
+ *     "compactToolRows": true
+ *   }
+ *
+ * Environment overrides (useful for tests and quick experiments):
+ *   PI_CC_CONFIG_FILE=/path/to/pi-cc.json
+ *   PI_CC_COMPACT_MESSAGES=0|1
+ *   PI_CC_COMPACT_TOOL_ROWS=0|1
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface PiCcConfig {
+	/** Two-line marker blocks instead of the padded card. */
+	compactMessages: boolean;
+	/** One-line tool results instead of Pi's "N lines returned" preview. */
+	compactToolRows: boolean;
+	/**
+	 * Keep pi-cc tools out of pi-cc-extensions' global tool styling so the
+	 * compact rows above are visible. Only names this extension added are
+	 * removed again when the setting is turned off.
+	 */
+	managePiCcExtensions: boolean;
+	/** Internal: names this extension added to pi-cc-extensions.json. */
+	managedExcludes?: string[];
+}
+
+export const DEFAULT_CONFIG: PiCcConfig = {
+	compactMessages: true,
+	compactToolRows: true,
+	managePiCcExtensions: true,
+};
+
+function envBool(name: string): boolean | undefined {
+	const raw = process.env[name];
+	if (raw === undefined) return undefined;
+	if (/^(0|false|off|no)$/i.test(raw)) return false;
+	if (/^(1|true|on|yes)$/i.test(raw)) return true;
+	return undefined;
+}
+
+/** The settings file shared by pi-cc-loop and pi-cc-monitor. */
+export function configPath(): string {
+	if (process.env.PI_CC_CONFIG_FILE) return process.env.PI_CC_CONFIG_FILE;
+	const agentDir = process.env.PI_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+	return path.join(agentDir, "pi-cc.json");
+}
+
+function readConfig(): PiCcConfig {
+	let file: Partial<PiCcConfig> = {};
+	try {
+		const parsed = JSON.parse(fs.readFileSync(configPath(), "utf8")) as unknown;
+		if (parsed && typeof parsed === "object") file = parsed as Partial<PiCcConfig>;
+	} catch {
+		// Missing or malformed files fall back to defaults.
+	}
+	return {
+		compactMessages:
+			envBool("PI_CC_COMPACT_MESSAGES") ??
+			(typeof file.compactMessages === "boolean" ? file.compactMessages : DEFAULT_CONFIG.compactMessages),
+		compactToolRows:
+			envBool("PI_CC_COMPACT_TOOL_ROWS") ??
+			(typeof file.compactToolRows === "boolean" ? file.compactToolRows : DEFAULT_CONFIG.compactToolRows),
+		managePiCcExtensions:
+			envBool("PI_CC_MANAGE_CCSTYLE") ??
+			(typeof file.managePiCcExtensions === "boolean"
+				? file.managePiCcExtensions
+				: DEFAULT_CONFIG.managePiCcExtensions),
+		managedExcludes: Array.isArray(file.managedExcludes)
+			? file.managedExcludes.filter((name): name is string => typeof name === "string")
+			: [],
+	};
+}
+
+let cached: PiCcConfig | undefined;
+
+/** Load the settings. Cached until `invalidateConfig` or `saveConfig`. */
+export function loadConfig(): PiCcConfig {
+	if (!cached) cached = readConfig();
+	return cached;
+}
+
+/** Forget the cached settings, e.g. after another extension changed the file. */
+export function invalidateConfig(): void {
+	cached = undefined;
+}
+
+/** Merge a patch into the settings file and update the cache. */
+export function saveConfig(patch: Partial<PiCcConfig>): PiCcConfig {
+	const next = { ...loadConfig(), ...patch };
+	const file = configPath();
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const temp = `${file}.tmp`;
+	fs.writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+	fs.renameSync(temp, file);
+	cached = next;
+	return next;
+}
+
+/**
+ * pi-cc-extensions' config file. That extension loads its config once at load
+ * time, so changes made here apply after `/reload`.
+ */
+export function piCcExtensionsConfigPath(): string {
+	const agentDir =
+		process.env.PI_CODING_AGENT_DIR ?? process.env.PI_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+	return process.env.PI_CC_EXTENSIONS_CONFIG_FILE ?? path.join(agentDir, "pi-cc-extensions.json");
+}
+
+/**
+ * Add or remove our tool names in pi-cc-extensions' `excludeRenderers`.
+ *
+ * Returns true when the file changed (the caller can tell the user to reload).
+ * Only names this extension added are removed again; a name the user put there
+ * themselves is left alone.
+ */
+export function syncPiCcExtensionsExcludes(toolNames: readonly string[], enabled: boolean): boolean {
+	// Another package may have written managedExcludes since our last read.
+	invalidateConfig();
+	const config = loadConfig();
+	if (!config.managePiCcExtensions) return false;
+	const file = piCcExtensionsConfigPath();
+	if (!fs.existsSync(file)) return false;
+
+	let raw: Record<string, unknown>;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+		raw = parsed as Record<string, unknown>;
+	} catch {
+		return false;
+	}
+
+	const current = Array.isArray(raw.excludeRenderers)
+		? raw.excludeRenderers.filter((name): name is string => typeof name === "string")
+		: [];
+	const managed = new Set(config.managedExcludes ?? []);
+	const next = new Set(current);
+	let changed = false;
+
+	for (const name of toolNames) {
+		if (enabled) {
+			if (!next.has(name)) {
+				next.add(name);
+				managed.add(name);
+				changed = true;
+			}
+		} else if (managed.has(name)) {
+			if (next.delete(name)) changed = true;
+			managed.delete(name);
+		}
+	}
+
+	if (!changed && managed.size === (config.managedExcludes ?? []).length) return false;
+
+	raw.excludeRenderers = [...next].sort((a, b) => a.localeCompare(b));
+	const temp = `${file}.tmp`;
+	fs.writeFileSync(temp, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+	fs.renameSync(temp, file);
+	saveConfig({ managedExcludes: [...managed].sort((a, b) => a.localeCompare(b)) });
+	return changed;
+}

package/cron.ts

@@ -0,0 +1,359 @@
+/**
+ * Minimal 5-field cron support for the pi-cc-loop extension.
+ *
+ * Fields: minute hour day-of-month month day-of-week
+ * Per-field syntax: `*`, `*\/N`, `a`, `a-b`, `a-b/N`, `a,b,c`
+ *
+ * Deliberately unsupported (same subset Claude Code accepts): `L`, `W`, `?`
+ * and name aliases such as `MON`.
+ */
+
+export interface CronFields {
+	minute: Set<number>;
+	hour: Set<number>;
+	dom: Set<number>;
+	month: Set<number>;
+	dow: Set<number>;
+	/** True when the day-of-month field was not `*`. */
+	domRestricted: boolean;
+	/** True when the day-of-week field was not `*`. */
+	dowRestricted: boolean;
+}
+
+interface FieldSpec {
+	name: string;
+	min: number;
+	max: number;
+}
+
+const FIELDS: FieldSpec[] = [
+	{ name: "minute", min: 0, max: 59 },
+	{ name: "hour", min: 0, max: 23 },
+	{ name: "day of month", min: 1, max: 31 },
+	{ name: "month", min: 1, max: 12 },
+	{ name: "day of week", min: 0, max: 7 },
+];
+
+export const CRON_FIELD_COUNT = FIELDS.length;
+
+function parseField(spec: FieldSpec, raw: string): Set<number> | null {
+	const out = new Set<number>();
+	const parts = raw.split(",");
+	for (const part of parts) {
+		const trimmed = part.trim();
+		if (!trimmed) return null;
+
+		const [rangePart, stepPart] = trimmed.split("/");
+		let step = 1;
+		if (stepPart !== undefined) {
+			if (!/^\d+$/.test(stepPart)) return null;
+			step = Number(stepPart);
+			if (step < 1) return null;
+		}
+
+		let start: number;
+		let end: number;
+		if (rangePart === "*") {
+			start = spec.min;
+			end = spec.max;
+		} else {
+			const m = /^(\d+)(?:-(\d+))?$/.exec(rangePart);
+			if (!m) return null;
+			start = Number(m[1]);
+			end = m[2] !== undefined ? Number(m[2]) : start;
+			if (end < start) return null;
+		}
+
+		if (start < spec.min || end > spec.max) return null;
+		for (let v = start; v <= end; v += step) {
+			// cron treats 7 and 0 as Sunday
+			out.add(spec.name === "day of week" && v === 7 ? 0 : v);
+		}
+	}
+	return out;
+}
+
+/** Parse a 5-field cron expression. Returns null when the expression is invalid. */
+export function parseCron(expression: string): CronFields | null {
+	const trimmed = expression.trim();
+	if (!trimmed) return null;
+	const tokens = trimmed.split(/\s+/);
+	if (tokens.length !== CRON_FIELD_COUNT) return null;
+
+	const parsed: Set<number>[] = [];
+	for (let i = 0; i < tokens.length; i++) {
+		const set = parseField(FIELDS[i], tokens[i]);
+		if (!set || set.size === 0) return null;
+		parsed.push(set);
+	}
+
+	return {
+		minute: parsed[0],
+		hour: parsed[1],
+		dom: parsed[2],
+		month: parsed[3],
+		dow: parsed[4],
+		domRestricted: tokens[2] !== "*",
+		dowRestricted: tokens[4] !== "*",
+	};
+}
+
+function dayMatches(fields: CronFields, date: Date): boolean {
+	const domOk = fields.dom.has(date.getDate());
+	const dowOk = fields.dow.has(date.getDay());
+	// vixie-cron semantics: when both day fields are restricted, either may match.
+	if (fields.domRestricted && fields.dowRestricted) return domOk || dowOk;
+	if (fields.domRestricted) return domOk;
+	if (fields.dowRestricted) return dowOk;
+	return true;
+}
+
+/**
+ * Next time the expression matches strictly after `from`, or null when nothing
+ * matches within the search window.
+ */
+export function nextFireAfter(
+	fields: CronFields,
+	from: Date,
+	limitDays = 366 * 4,
+): Date | null {
+	const cursor = new Date(from.getTime());
+	cursor.setSeconds(0, 0);
+	cursor.setMinutes(cursor.getMinutes() + 1);
+	const limit = from.getTime() + limitDays * 24 * 60 * 60 * 1000;
+
+	while (cursor.getTime() <= limit) {
+		if (!fields.month.has(cursor.getMonth() + 1)) {
+			cursor.setMonth(cursor.getMonth() + 1, 1);
+			cursor.setHours(0, 0, 0, 0);
+			continue;
+		}
+		if (!dayMatches(fields, cursor)) {
+			cursor.setDate(cursor.getDate() + 1);
+			cursor.setHours(0, 0, 0, 0);
+			continue;
+		}
+		if (!fields.hour.has(cursor.getHours())) {
+			cursor.setHours(cursor.getHours() + 1, 0, 0, 0);
+			continue;
+		}
+		if (!fields.minute.has(cursor.getMinutes())) {
+			cursor.setMinutes(cursor.getMinutes() + 1, 0, 0);
+			continue;
+		}
+		return cursor;
+	}
+	return null;
+}
+
+/** True when the expression can never match (e.g. February 30th). */
+export function isUnreachable(expression: string): boolean {
+	const fields = parseCron(expression);
+	if (!fields) return true;
+	// Look a year ahead; if nothing matches, the expression is dead.
+	return nextFireAfter(fields, new Date(), 366) === null;
+}
+
+export interface IntervalSpec {
+	/** Number of seconds the schedule actually uses. */
+	seconds: number;
+	/** Cron expression that implements the interval. */
+	cron: string;
+	/** Human readable cadence, e.g. "every 5 minutes". */
+	human: string;
+	/** True when the requested interval had to be adjusted. */
+	adjusted: boolean;
+	/** What the user asked for, in seconds. */
+	requestedSeconds: number;
+	/** Human readable explanation of the adjustment, for the user. */
+	note?: string;
+}
+
+const UNIT_SECONDS: Record<string, number> = {
+	s: 1,
+	m: 60,
+	h: 3600,
+	d: 86400,
+};
+
+const UNIT_NAMES: Record<string, [string, string]> = {
+	s: ["second", "seconds"],
+	m: ["minute", "minutes"],
+	h: ["hour", "hours"],
+	d: ["day", "days"],
+};
+
+/**
+ * The divisor of `total` closest to `n`.
+ *
+ * Claude Code rounds a non-dividing interval to the nearest clean one: "If the
+ * interval doesn't cleanly divide its unit, round to the nearest clean interval
+ * and tell the user what you rounded to."
+ */
+function nearestDivisor(n: number, total: number): number {
+	let best = 1;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (let d = 1; d <= total; d++) {
+		if (total % d !== 0) continue;
+		const distance = Math.abs(d - n);
+		if (distance < bestDistance) {
+			best = d;
+			bestDistance = distance;
+		}
+	}
+	return best;
+}
+
+/**
+ * Convert a duration into a cron expression, following Claude Code's rule:
+ *
+ *   "Supported suffixes: `s` -> ceil to nearest minute, `m` (minutes),
+ *    `h` (hours), `d` (days). Examples: `5m` -> a 5 minute step, `1h` -> `0 * * * *`,
+ *    `1d` -> `0 0 * * *`. If the interval doesn't cleanly divide its unit, round to the
+ *    nearest clean interval and tell the user what you rounded to."
+ */
+export function intervalToCron(seconds: number): IntervalSpec | null {
+	if (!Number.isFinite(seconds) || seconds <= 0) return null;
+
+	// Sub-minute: the scheduler's granularity is one minute, so round up.
+	if (seconds < 60) {
+		return {
+			seconds: 60,
+			cron: "* * * * *",
+			human: "every minute",
+			adjusted: true,
+			requestedSeconds: seconds,
+			note: `${seconds}s rounded up to 1 minute (the scheduler's minimum granularity is 1 minute)`,
+		};
+	}
+
+	if (seconds < 3600) {
+		const requested = Math.round(seconds / 60);
+		const minutes = nearestDivisor(requested, 60);
+		return {
+			seconds: minutes * 60,
+			cron: `*/${minutes} * * * *`,
+			human: `every ${minutes} minute${minutes === 1 ? "" : "s"}`,
+			adjusted: minutes !== requested,
+			requestedSeconds: seconds,
+			...(minutes !== requested
+				? { note: `${requested}m rounded to ${minutes}m, the nearest clean interval` }
+				: {}),
+		};
+	}
+
+	if (seconds < 86400) {
+		const requested = Math.round(seconds / 3600);
+		const hours = nearestDivisor(requested, 24);
+		return {
+			seconds: hours * 3600,
+			cron: hours === 1 ? "0 * * * *" : `0 */${hours} * * *`,
+			human: `every ${hours} hour${hours === 1 ? "" : "s"}`,
+			adjusted: hours !== requested,
+			requestedSeconds: seconds,
+			...(hours !== requested
+				? { note: `${requested}h rounded to ${hours}h, the nearest clean interval` }
+				: {}),
+		};
+	}
+
+	const days = Math.max(1, Math.round(seconds / 86400));
+	return {
+		seconds: days * 86400,
+		cron: days === 1 ? "0 0 * * *" : `0 0 */${days} * *`,
+		human: days === 1 ? "every day" : `every ${days} days`,
+		adjusted: days * 86400 !== seconds,
+		requestedSeconds: seconds,
+	};
+}
+
+/** Parse a duration token such as `5m`, `30s`, `2h`, `1d`. */
+export function parseIntervalToken(token: string): number | null {
+	const m = /^(\d+)\s*([smhd])$/i.exec(token.trim());
+	if (!m) return null;
+	const unit = m[2].toLowerCase();
+	const amount = Number(m[1]);
+	if (!Number.isFinite(amount) || amount <= 0) return null;
+	return amount * UNIT_SECONDS[unit];
+}
+
+/** Parse `every 20m` / `every 5 minutes` / `every 2 hours` style clauses. */
+export function parseEveryClause(input: string): { interval: number; prompt: string } | null {
+	const m = /\bevery\s+(\d+)\s*([a-z]+)\s*$/i.exec(input.trim());
+	if (!m) return null;
+	const amount = Number(m[1]);
+	const word = m[2].toLowerCase();
+	let unitSeconds: number | undefined;
+	for (const [key, names] of Object.entries(UNIT_NAMES)) {
+		if (names[0] === word || names[1] === word) {
+			unitSeconds = UNIT_SECONDS[key];
+			break;
+		}
+	}
+	// Single letter units, e.g. "every 20m".
+	if (unitSeconds === undefined && word.length === 1 && word in UNIT_SECONDS) {
+		unitSeconds = UNIT_SECONDS[word];
+	}
+	if (unitSeconds === undefined) return null;
+	const prompt = input.trim().slice(0, m.index).trim();
+	return { interval: amount * unitSeconds, prompt };
+}
+
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+
+/**
+ * A human readable cadence for a cron expression, the way Claude Code
+ * reports it ("Every minute", "Every 5 minutes", "Daily at 9:00 AM").
+ */
+export function humanSchedule(expression: string): string {
+	const fields = parseCron(expression);
+	if (!fields) return expression;
+	const [minute, hour, dom, month, dow] = expression.trim().split(/\s+/);
+	const everyMinute = minute === "*" && hour === "*" && dom === "*" && month === "*" && dow === "*";
+	if (everyMinute) return "Every minute";
+
+	const step = /^\*\/(\d+)$/.exec(minute);
+	if (step && hour === "*" && dom === "*" && month === "*" && dow === "*") {
+		const n = Number(step[1]);
+		return n === 1 ? "Every minute" : `Every ${n} minutes`;
+	}
+
+	const clock = clockText(minute, hour);
+	if (dom === "*" && month === "*" && dow === "*") {
+		if (hour === "*") return `Every hour at :${minute.padStart(2, "0")}`;
+		if (minute === "0") return `Hourly`;
+		return `Daily at ${clock}`;
+	}
+	if (month === "*" && dow === "*") return `On day ${dom} at ${clock}`;
+	if (month === "*") {
+		const days = dow
+			.split(",")
+			.map((d) => DAY_NAMES[Number(d) % 7])
+			.join(", ");
+		return `Every ${days} at ${clock}`;
+	}
+	return expression;
+}
+
+/** "9:05 AM" style time for the minute and hour fields. */
+function clockText(minute: string, hour: string): string {
+	if (hour === "*") return `:${minute.padStart(2, "0")}`;
+	const h = Number(hour);
+	const suffix = h < 12 ? "AM" : "PM";
+	const display = h % 12 === 0 ? 12 : h % 12;
+	return `${display}:${minute.padStart(2, "0")} ${suffix}`;
+}
+
+/** Human readable summary of a cron expression. */
+export function describeCron(expression: string): string {
+	const fields = parseCron(expression);
+	if (!fields) return expression;
+	const [minute, hour, dom, month, dow] = expression.trim().split(/\s+/);
+	const parts: string[] = [];
+	if (minute !== "*") parts.push(`minute ${minute}`);
+	if (hour !== "*") parts.push(`hour ${hour}`);
+	if (dom !== "*") parts.push(`day-of-month ${dom}`);
+	if (month !== "*") parts.push(`month ${month}`);
+	if (dow !== "*") parts.push(`day-of-week ${dow}`);
+	return parts.length ? parts.join(", ") : "every minute";
+}