@maxiaochao/pi-toolkit 0.10.6 → 0.10.7

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-09 - v0.10.7
+
+- bundle scheduler v0.1.0: add session-scoped interval prompts with Agent and user controls
+- Add the bundled and independently installable `@maxiaochao/pi-scheduler` package for session-scoped interval prompts, manual triggering, lightweight TUI status, and shared Agent/user controls.
+
 ## 2026-10-09 - v0.10.6
 
 - bundle herdr-subagents v0.4.3: add per-run status, neutral analyst persona, and tool-agnostic Agent Team protocol

package/README.md

@@ -34,6 +34,7 @@ Restart Pi after updating. The `todo` tool and widget will no longer load. `pi u
 | [pi-cache-export](packages/cache-export/README.md) | Tau-aligned interactive cache dashboard for Pi sessions | `pi install npm:@maxiaochao/pi-cache-export` | `pi update npm:@maxiaochao/pi-cache-export` |
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` |
 | [pi-herdr-subagents](packages/herdr-subagents/README.md) | Interactive Herdr Pi Agents with bounded concurrency, direct navigation, and recovery | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` |
+| [pi-scheduler](packages/scheduler/README.md) | Session-scoped interval prompts with Agent and `/schedule` controls | `pi install npm:@maxiaochao/pi-scheduler` | `pi update npm:@maxiaochao/pi-scheduler` |
 | [pi-worktree](packages/worktree/README.md) | Worktree CLI, completion, installer, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.6",
-  "description": "Personal pi coding agent toolkit: /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
+  "version": "0.10.7",
+  "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
     "packages/*"
@@ -15,6 +15,7 @@
     "packages/cache-export",
     "packages/codex-edit",
     "packages/herdr-subagents",
+    "packages/scheduler",
     "packages/worktree",
     "themes",
     "README.md",
@@ -32,7 +33,8 @@
       "./packages/cache-export/extensions/cache-export.ts",
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
-      "./packages/herdr-subagents/extensions/herdr-subagents.ts"
+      "./packages/herdr-subagents/extensions/herdr-subagents.ts",
+      "./packages/scheduler/extensions/scheduler.ts"
     ],
     "skills": [
       "./skills",
@@ -55,8 +57,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts",
+    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/scheduler test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/packages/scheduler/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 2026-10-09 - v0.1.0
+
+- add session-scoped interval prompts with Agent and user controls
+- Add session-scoped interval prompts controlled by both the Agent tool and `/schedule` command.
+- Add manual trigger, cancellation, missed-tick coalescing, and lightweight TUI status.

package/packages/scheduler/README.md

@@ -0,0 +1,57 @@
+# Pi Scheduler
+
+Session-scoped interval prompts for Pi. Scheduler does one thing: at a fixed interval, queue a prompt for the current main agent at a safe turn boundary.
+
+![Scheduler status and commands](docs/screenshot.png)
+
+![Scheduler demo](docs/demo.gif)
+
+## Why
+
+Use Scheduler when the agent should periodically re-check CI, logs, a review, or another changing condition. It is not Cron, a background process manager, or a durable workflow engine.
+
+## Install
+
+```bash
+pi install npm:@maxiaochao/pi-scheduler
+```
+
+Update it with `pi update npm:@maxiaochao/pi-scheduler`.
+
+## Agent tool
+
+```text
+schedule({ action: "add", every: "5m", prompt: "Check CI; report completion or failure." })
+schedule({ action: "list" })
+schedule({ action: "trigger", id: "schedule-1" })
+schedule({ action: "cancel", id: "schedule-1" })
+```
+
+## User command
+
+```text
+/schedule add 5m Check CI; report completion or failure.
+/schedule list
+/schedule trigger schedule-1
+/schedule cancel schedule-1
+```
+
+Manual trigger queues one prompt and does not move the regular next time. The TUI status line shows the active count and next trigger.
+
+## Semantics and limits
+
+- Intervals accept `s`, `m`, `h`, and `d`, from 1 second through 7 days.
+- Prompts use Pi `followUp`: an active agent turn finishes before the scheduled prompt runs.
+- At most one prompt per schedule remains pending; missed intervals coalesce instead of flooding the queue.
+- Schedules live only in the current session and are cleared on new/resume/fork/reload/quit.
+- Cancel stops future timer events. Pi cannot selectively withdraw a prompt already in its follow-up queue.
+- Timing is best-effort, not real-time. Recursive `setTimeout` uses absolute target times to avoid cumulative drift.
+- Calendar expressions, time zones, persistence, process monitoring, and script notifications are intentionally out of scope.
+
+## Remove
+
+```bash
+pi remove npm:@maxiaochao/pi-scheduler
+```
+
+Do not install both the standalone package and a toolkit release that already bundles Scheduler, or the tool and command will be registered twice.

package/packages/scheduler/TESTING.md

@@ -0,0 +1,19 @@
+# Testing Pi Scheduler
+
+Run from the repository root:
+
+```bash
+npm --prefix packages/scheduler test
+npm --prefix packages/scheduler run load-test
+npm pack ./packages/scheduler --dry-run
+```
+
+The deterministic core test uses a fake clock to verify duration parsing, absolute-time cadence, timed triggering, missed-tick coalescing, manual triggering, dropped-follow-up release, and cancellation. The extension test verifies tool/command parity, manual follow-up delivery, message-specific pending acknowledgement, settled-run fallback cleanup, TUI status, duplicate suppression, and shutdown timer cleanup.
+
+For a manual TUI check, run Pi with `-e ./packages/scheduler/extensions/scheduler.ts`, create a short schedule, confirm the status line appears, and verify the prompt starts only after the current turn settles.
+
+Regenerate package media with:
+
+```bash
+node scripts/capture-package-media.mjs
+```

package/packages/scheduler/extensions/scheduler.ts

@@ -0,0 +1,133 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { Scheduler, systemClock, type ScheduleSnapshot } from "../src/scheduler.ts";
+
+const Params = Type.Object({
+	action: StringEnum(["add", "list", "trigger", "cancel"] as const),
+	every: Type.Optional(Type.String({ description: "Interval for add, for example 30s, 5m, or 1h30m" })),
+	prompt: Type.Optional(Type.String({ description: "Prompt delivered to the main agent on each trigger" })),
+	id: Type.Optional(Type.String({ description: "Schedule ID for trigger or cancel" })),
+});
+
+function formatTime(timestamp: number): string {
+	return new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" });
+}
+
+function formatList(schedules: ScheduleSnapshot[]): string {
+	if (schedules.length === 0) return "No active schedules.";
+	return schedules.map((item) =>
+		`${item.id} · every ${item.every} · next ${formatTime(item.nextRunAt)}${item.pending ? " · prompt pending" : ""}\n  ${item.prompt}`,
+	).join("\n");
+}
+
+function parseCommand(input: string): { action: "add" | "list" | "trigger" | "cancel"; every?: string; prompt?: string; id?: string } {
+	const text = input.trim();
+	if (!text || text === "list") return { action: "list" };
+	const [action, first, ...rest] = text.split(/\s+/);
+	if (action === "add") return { action, every: first, prompt: rest.join(" ") };
+	if (action === "trigger" || action === "cancel") return { action, id: first };
+	throw new Error("usage: /schedule add <interval> <prompt> | list | trigger <id> | cancel <id>");
+}
+
+export default function (pi: ExtensionAPI) {
+	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1") return;
+	let context: ExtensionContext | undefined;
+
+	const refreshStatus = () => {
+		if (!context?.hasUI) return;
+		const schedules = scheduler.list();
+		const next = schedules[0];
+		context.ui.setStatus("scheduler", next ? `⏱ ${schedules.length} schedule${schedules.length === 1 ? "" : "s"} · next ${formatTime(next.nextRunAt)}` : undefined);
+	};
+
+	const scheduler = new Scheduler({
+		clock: systemClock,
+		onChange: refreshStatus,
+		onTrigger(schedule, source) {
+			pi.sendMessage({
+				customType: "scheduler-trigger",
+				content: `[Scheduled prompt: ${schedule.id}; source=${source}]\n${schedule.prompt}`,
+				display: true,
+				details: { scheduleId: schedule.id, source, every: schedule.every },
+			}, { triggerTurn: true, deliverAs: "followUp" });
+		},
+	});
+
+	const perform = (params: { action: "add" | "list" | "trigger" | "cancel"; every?: string; prompt?: string; id?: string }) => {
+		if (params.action === "add") {
+			if (!params.every || !params.prompt) throw new Error("add requires every and prompt");
+			const item = scheduler.add(params.every, params.prompt);
+			return `Created ${item.id}: every ${item.every}; next ${formatTime(item.nextRunAt)}.`;
+		}
+		if (params.action === "list") return formatList(scheduler.list());
+		if (!params.id) throw new Error(`${params.action} requires id`);
+		if (params.action === "cancel") {
+			if (!scheduler.cancel(params.id)) throw new Error(`unknown schedule: ${params.id}`);
+			return `Cancelled ${params.id}. Already queued prompts cannot be withdrawn.`;
+		}
+		const result = scheduler.trigger(params.id);
+		if (!result.ok) {
+			if (result.reason === "already-pending") throw new Error(`${params.id} already has a pending prompt`);
+			throw new Error(`unknown schedule: ${params.id}`);
+		}
+		return `Triggered ${params.id}; its regular next time is unchanged.`;
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		context = ctx;
+		refreshStatus();
+	});
+	pi.on("message_start", async (event) => {
+		if (event.message.role !== "custom" || event.message.customType !== "scheduler-trigger") return;
+		const details = event.message.details as { scheduleId?: unknown } | undefined;
+		if (typeof details?.scheduleId === "string") scheduler.acknowledge(details.scheduleId);
+	});
+	pi.on("agent_settled", async () => {
+		// A queued follow-up can be cleared by Pi before it produces message_start.
+		// Once the run is fully settled, any still-pending scheduler message is gone.
+		scheduler.releaseUndelivered();
+	});
+	pi.on("session_shutdown", async (_event, ctx) => {
+		scheduler.clear();
+		if (ctx.hasUI) ctx.ui.setStatus("scheduler", undefined);
+		context = undefined;
+	});
+
+	pi.registerTool({
+		name: "schedule",
+		label: "Schedule",
+		description: "Manage session-scoped interval prompts for the main agent. Use add when the user asks the agent to check something repeatedly. Use trigger for one immediate check without changing the regular cadence. Schedules end with the current session.",
+		parameters: Params,
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+		async execute(_toolCallId, params) {
+			try {
+				const text = perform(params);
+				return { content: [{ type: "text" as const, text }], details: { ...params, schedules: scheduler.list() } };
+			} catch (error) {
+				const text = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text" as const, text: `Error: ${text}` }], details: { ...params, error: text }, isError: true };
+			}
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("schedule "))}${theme.fg("muted", args.action)}`, 0, 0);
+		},
+		renderResult(result, _options, theme) {
+			const item = result.content[0];
+			return new Text(theme.fg(result.isError ? "error" : "muted", item?.type === "text" ? item.text : ""), 0, 0);
+		},
+	});
+
+	pi.registerCommand("schedule", {
+		description: "Add, list, trigger, or cancel session-scoped interval prompts",
+		handler: async (args, ctx) => {
+			try {
+				const text = perform(parseCommand(args));
+				ctx.ui.notify(text, "info");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+}

package/packages/scheduler/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@maxiaochao/pi-scheduler",
+  "version": "0.1.0",
+  "description": "Session-scoped interval prompts for Pi agents.",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "scheduler"],
+  "files": ["extensions", "src", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
+    "directory": "packages/scheduler"
+  },
+  "pi": { "extensions": ["./extensions/scheduler.ts"] },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types tests/scheduler-core.mjs && node --experimental-strip-types tests/scheduler-extension.mjs",
+    "load-test": "pi -ne -e ./extensions/scheduler.ts"
+  },
+  "publishConfig": { "access": "public" }
+}

package/packages/scheduler/src/scheduler.ts

@@ -0,0 +1,171 @@
+export interface Clock {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+export interface ScheduleSnapshot {
+	id: string;
+	every: string;
+	intervalMs: number;
+	prompt: string;
+	nextRunAt: number;
+	pending: boolean;
+}
+
+interface Schedule extends ScheduleSnapshot {
+	timer?: unknown;
+}
+
+export interface TriggerResult {
+	ok: boolean;
+	reason?: "not-found" | "already-pending";
+	schedule?: ScheduleSnapshot;
+}
+
+const DURATION_PART = /(\d+)(ms|s|m|h|d)/gy;
+const MAX_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function parseDuration(input: string): number {
+	const value = input.trim().toLowerCase();
+	if (!value) throw new Error("interval is required");
+	let total = 0;
+	let offset = 0;
+	for (const match of value.matchAll(DURATION_PART)) {
+		if (match.index !== offset) throw new Error(`invalid interval: ${input}`);
+		const amount = Number(match[1]);
+		const unit = match[2];
+		const multiplier = unit === "ms" ? 1 : unit === "s" ? 1_000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+		total += amount * multiplier;
+		offset = match.index + match[0].length;
+	}
+	if (offset !== value.length || total < 1_000 || total > MAX_INTERVAL_MS) {
+		throw new Error("interval must be between 1s and 7d (examples: 30s, 5m, 1h30m)");
+	}
+	return total;
+}
+
+export class Scheduler {
+	private readonly clock: Clock;
+	private readonly onTrigger: (schedule: ScheduleSnapshot, source: "timer" | "manual") => void;
+	private readonly onChange: () => void;
+	private readonly schedules = new Map<string, Schedule>();
+	private nextId = 1;
+
+	constructor(options: {
+		clock: Clock;
+		onTrigger: (schedule: ScheduleSnapshot, source: "timer" | "manual") => void;
+		onChange?: () => void;
+	}) {
+		this.clock = options.clock;
+		this.onTrigger = options.onTrigger;
+		this.onChange = options.onChange ?? (() => {});
+	}
+
+	add(every: string, prompt: string): ScheduleSnapshot {
+		const intervalMs = parseDuration(every);
+		const normalizedPrompt = prompt.trim();
+		if (!normalizedPrompt) throw new Error("prompt is required");
+		const schedule: Schedule = {
+			id: `schedule-${this.nextId++}`,
+			every: every.trim(),
+			intervalMs,
+			prompt: normalizedPrompt,
+			nextRunAt: this.clock.now() + intervalMs,
+			pending: false,
+		};
+		this.schedules.set(schedule.id, schedule);
+		this.arm(schedule);
+		this.onChange();
+		return this.snapshot(schedule);
+	}
+
+	list(): ScheduleSnapshot[] {
+		return [...this.schedules.values()]
+			.sort((left, right) => left.nextRunAt - right.nextRunAt || left.id.localeCompare(right.id))
+			.map((schedule) => this.snapshot(schedule));
+	}
+
+	trigger(id: string): TriggerResult {
+		const schedule = this.schedules.get(id);
+		if (!schedule) return { ok: false, reason: "not-found" };
+		if (schedule.pending) return { ok: false, reason: "already-pending", schedule: this.snapshot(schedule) };
+		this.fire(schedule, "manual");
+		return { ok: true, schedule: this.snapshot(schedule) };
+	}
+
+	cancel(id: string): boolean {
+		const schedule = this.schedules.get(id);
+		if (!schedule) return false;
+		if (schedule.timer !== undefined) this.clock.clearTimeout(schedule.timer);
+		this.schedules.delete(id);
+		this.onChange();
+		return true;
+	}
+
+	acknowledge(id: string): boolean {
+		const schedule = this.schedules.get(id);
+		if (!schedule?.pending) return false;
+		schedule.pending = false;
+		this.onChange();
+		return true;
+	}
+
+	releaseUndelivered(): number {
+		let released = 0;
+		for (const schedule of this.schedules.values()) {
+			if (!schedule.pending) continue;
+			schedule.pending = false;
+			released += 1;
+		}
+		if (released > 0) this.onChange();
+		return released;
+	}
+
+	clear(): void {
+		for (const schedule of this.schedules.values()) {
+			if (schedule.timer !== undefined) this.clock.clearTimeout(schedule.timer);
+		}
+		this.schedules.clear();
+		this.onChange();
+	}
+
+	private arm(schedule: Schedule): void {
+		const delay = Math.max(0, schedule.nextRunAt - this.clock.now());
+		schedule.timer = this.clock.setTimeout(() => this.tick(schedule.id), delay);
+	}
+
+	private tick(id: string): void {
+		const schedule = this.schedules.get(id);
+		if (!schedule) return;
+		const now = this.clock.now();
+		do schedule.nextRunAt += schedule.intervalMs;
+		while (schedule.nextRunAt <= now);
+		if (!schedule.pending) this.fire(schedule, "timer");
+		this.arm(schedule);
+		this.onChange();
+	}
+
+	private fire(schedule: Schedule, source: "timer" | "manual"): void {
+		schedule.pending = true;
+		this.onTrigger(this.snapshot(schedule), source);
+		this.onChange();
+	}
+
+	private snapshot(schedule: Schedule): ScheduleSnapshot {
+		return {
+			id: schedule.id,
+			every: schedule.every,
+			intervalMs: schedule.intervalMs,
+			prompt: schedule.prompt,
+			nextRunAt: schedule.nextRunAt,
+			pending: schedule.pending,
+		};
+	}
+}
+
+export const systemClock: Clock = {
+	now: () => Date.now(),
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};

package/packages/scheduler/tests/scheduler-core.mjs

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { Scheduler, parseDuration } from "../src/scheduler.ts";
+
+class FakeClock {
+	nowMs = 1_000_000;
+	nextHandle = 1;
+	timers = new Map();
+	now() { return this.nowMs; }
+	setTimeout(callback, delayMs) {
+		const handle = this.nextHandle++;
+		this.timers.set(handle, { at: this.nowMs + delayMs, callback });
+		return handle;
+	}
+	clearTimeout(handle) { this.timers.delete(handle); }
+	advance(ms) {
+		this.nowMs += ms;
+		while (true) {
+			const due = [...this.timers.entries()].filter(([, timer]) => timer.at <= this.nowMs).sort((a, b) => a[1].at - b[1].at)[0];
+			if (!due) break;
+			this.timers.delete(due[0]);
+			due[1].callback();
+		}
+	}
+}
+
+assert.equal(parseDuration("5m"), 300_000);
+assert.equal(parseDuration("1h30m"), 5_400_000);
+assert.throws(() => parseDuration("cron * * * * *"), /interval/);
+assert.throws(() => parseDuration("500ms"), /between 1s and 7d/);
+
+const clock = new FakeClock();
+const triggers = [];
+let changes = 0;
+const scheduler = new Scheduler({ clock, onTrigger: (schedule, source) => triggers.push({ schedule, source }), onChange: () => { changes += 1; } });
+const added = scheduler.add("5m", "Check CI and report only if finished or failed");
+assert.equal(added.id, "schedule-1");
+assert.equal(added.nextRunAt, 1_300_000);
+assert.equal(scheduler.list().length, 1);
+
+clock.advance(300_000);
+assert.equal(triggers.length, 1);
+assert.equal(triggers[0].source, "timer");
+assert.equal(scheduler.list()[0].pending, true);
+assert.equal(scheduler.list()[0].nextRunAt, 1_600_000);
+
+clock.advance(900_000);
+assert.equal(triggers.length, 1, "missed intervals coalesce while one prompt is pending");
+assert.equal(scheduler.list()[0].nextRunAt, 2_500_000, "absolute cadence skips missed intervals without drift");
+assert.equal(scheduler.acknowledge(added.id), true);
+assert.equal(scheduler.acknowledge(added.id), false);
+assert.equal(scheduler.trigger(added.id).ok, true);
+assert.equal(triggers.at(-1).source, "manual");
+assert.equal(scheduler.list()[0].nextRunAt, 2_500_000, "manual trigger preserves regular cadence");
+assert.deepEqual(scheduler.trigger(added.id).reason, "already-pending");
+assert.equal(scheduler.releaseUndelivered(), 1);
+assert.equal(scheduler.releaseUndelivered(), 0);
+assert.equal(scheduler.trigger(added.id).ok, true, "a settled run releases a follow-up that never entered message_start");
+
+assert.equal(scheduler.cancel(added.id), true);
+assert.equal(scheduler.cancel(added.id), false);
+assert.equal(scheduler.list().length, 0);
+assert.ok(changes >= 5);
+console.log("Scheduler core tests passed");

package/packages/scheduler/tests/scheduler-extension.mjs

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import registerScheduler from "../extensions/scheduler.ts";
+
+const handlers = new Map();
+const commands = new Map();
+const messages = [];
+const statuses = new Map();
+let tool;
+const originalSetTimeout = globalThis.setTimeout;
+const originalClearTimeout = globalThis.clearTimeout;
+let nextTimer = 1;
+const timers = new Map();
+globalThis.setTimeout = (callback, delayMs) => {
+	const id = nextTimer++;
+	timers.set(id, { callback, delayMs });
+	return id;
+};
+globalThis.clearTimeout = (id) => timers.delete(id);
+const pi = {
+	on(name, handler) { handlers.set(name, handler); },
+	registerTool(definition) { tool = definition; },
+	registerCommand(name, definition) { commands.set(name, definition); },
+	sendMessage(message, options) { messages.push({ message, options }); },
+};
+const childGuard = process.env.PI_HERDR_SUBAGENTS_CHILD;
+delete process.env.PI_HERDR_SUBAGENTS_CHILD;
+try {
+	registerScheduler(pi);
+} finally {
+	if (childGuard === undefined) delete process.env.PI_HERDR_SUBAGENTS_CHILD;
+	else process.env.PI_HERDR_SUBAGENTS_CHILD = childGuard;
+}
+const notifications = [];
+const asAppMessage = ({ message }) => ({ ...message, role: "custom" });
+const context = {
+	hasUI: true,
+	ui: {
+		setStatus(key, value) { if (value === undefined) statuses.delete(key); else statuses.set(key, value); },
+		notify(message, level) { notifications.push({ message, level }); },
+	},
+};
+await handlers.get("session_start")({}, context);
+assert.ok(tool);
+assert.ok(commands.has("schedule"));
+
+const add = await tool.execute("add", { action: "add", every: "1h", prompt: "Check CI" });
+assert.match(add.content[0].text, /Created schedule-1/);
+assert.match(statuses.get("scheduler"), /1 schedule/);
+
+const trigger = await tool.execute("trigger", { action: "trigger", id: "schedule-1" });
+assert.match(trigger.content[0].text, /Triggered schedule-1/);
+assert.equal(messages.length, 1);
+assert.deepEqual(messages[0].options, { triggerTurn: true, deliverAs: "followUp" });
+assert.match(messages[0].message.content, /\[Scheduled prompt: schedule-1; source=manual\]\nCheck CI/);
+const duplicate = await tool.execute("trigger-again", { action: "trigger", id: "schedule-1" });
+assert.equal(duplicate.isError, true);
+
+await handlers.get("message_start")({ message: { role: "custom", customType: "other", details: { scheduleId: "schedule-1" } } });
+assert.equal((await tool.execute("still-pending", { action: "trigger", id: "schedule-1" })).isError, true, "unrelated custom messages do not acknowledge a schedule");
+await handlers.get("message_start")({ message: asAppMessage(messages[0]) });
+await commands.get("schedule").handler("trigger schedule-1", context);
+assert.equal(messages.length, 2);
+assert.match(notifications.at(-1).message, /regular next time is unchanged/);
+await commands.get("schedule").handler("list", context);
+assert.match(notifications.at(-1).message, /schedule-1/);
+
+await handlers.get("agent_settled")({ aborted: false });
+await commands.get("schedule").handler("trigger schedule-1", context);
+assert.equal(messages.length, 3, "settlement releases a queued scheduler message that never reached message_start");
+await handlers.get("message_start")({ message: asAppMessage(messages[2]) });
+await commands.get("schedule").handler("cancel schedule-1", context);
+assert.match(notifications.at(-1).message, /Already queued prompts cannot be withdrawn/);
+assert.equal(statuses.has("scheduler"), false);
+await tool.execute("shutdown-add", { action: "add", every: "2h", prompt: "Check deployment" });
+assert.equal(timers.size, 1, "active schedule owns one timer");
+await handlers.get("session_shutdown")({}, context);
+assert.equal(statuses.has("scheduler"), false);
+assert.equal(timers.size, 0, "session shutdown clears active timers");
+globalThis.setTimeout = originalSetTimeout;
+globalThis.clearTimeout = originalClearTimeout;
+console.log("Scheduler extension integration tests passed");