@maxiaochao/pi-toolkit 0.10.6 → 0.10.8

package/packages/scheduler/README.md

@@ -0,0 +1,59 @@
+# 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" })
+schedule({ action: "clear" })
+```
+
+## User command
+
+```text
+/schedule add 5m Check CI; report completion or failure.
+/schedule list
+/schedule trigger schedule-1
+/schedule cancel schedule-1
+/schedule clear
+```
+
+Manual trigger queues one prompt and does not move the regular next time. A multi-line widget above the editor shows one row per active schedule with its ID, interval, next trigger, pending state, and prompt. Herdr Fleet remains below the editor, so the two live displays do not compete for the same area or overwrite each other.
+
+## 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 one schedule; clear stops all active schedules. 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, single cancellation, and clear-all timer cleanup. The extension test verifies tool/command parity, manual follow-up delivery, message-specific pending acknowledgement, settled-run fallback cleanup, the above-editor multi-line widget, coexistence with the below-editor Herdr Fleet, duplicate suppression, clear, 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,206 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } 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", "clear"] 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");
+}
+
+type ScheduleAction = "add" | "list" | "trigger" | "cancel" | "clear";
+
+function parseCommand(input: string): { action: ScheduleAction; 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 };
+	if (action === "clear") return { action };
+	throw new Error("usage: /schedule add <interval> <prompt> | list | trigger <id> | cancel <id> | clear");
+}
+
+const WIDGET_KEY = "scheduler";
+
+export class ScheduleWidget {
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+	private readonly getSchedules: () => ScheduleSnapshot[];
+	private readonly theme: Theme;
+
+	constructor(getSchedules: () => ScheduleSnapshot[], theme: Theme) {
+		this.getSchedules = getSchedules;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const schedules = this.getSchedules();
+		this.cachedLines = [
+			truncateToWidth(this.theme.fg("accent", `⏱ ${schedules.length} active schedule${schedules.length === 1 ? "" : "s"}`), width),
+			...schedules.map((item) => {
+				const marker = item.pending ? this.theme.fg("warning", "●") : this.theme.fg("dim", "○");
+				const state = item.pending ? " · pending" : "";
+				return truncateToWidth(`  ${marker} ${this.theme.fg("accent", item.id)} · ${item.every} · next ${formatTime(item.nextRunAt)}${state} · ${this.theme.fg("text", item.prompt)}`, width);
+			}),
+		];
+		this.cachedWidth = width;
+		return this.cachedLines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}
+
+interface MountedWidget {
+	component: ScheduleWidget;
+	tui: { requestRender(): void };
+}
+
+export default function (pi: ExtensionAPI) {
+	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1") return;
+	let context: ExtensionContext | undefined;
+	let mountedWidget: MountedWidget | undefined;
+
+	const refreshUI = () => {
+		if (!context?.hasUI) return;
+		const schedules = scheduler.list();
+		if (context.mode !== "tui") {
+			const next = schedules[0];
+			context.ui.setStatus(WIDGET_KEY, next ? `⏱ ${schedules.length} schedule${schedules.length === 1 ? "" : "s"} · next ${formatTime(next.nextRunAt)}` : undefined);
+			return;
+		}
+		context.ui.setStatus(WIDGET_KEY, undefined);
+		if (schedules.length === 0) {
+			if (mountedWidget) {
+				context.ui.setWidget(WIDGET_KEY, undefined);
+				mountedWidget.tui.requestRender();
+				mountedWidget = undefined;
+			}
+			return;
+		}
+		if (mountedWidget) {
+			mountedWidget.component.invalidate();
+			mountedWidget.tui.requestRender();
+			return;
+		}
+		context.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+			const component = new ScheduleWidget(() => scheduler.list(), theme);
+			mountedWidget = { component, tui };
+			return component;
+		}, { placement: "aboveEditor" });
+	};
+
+	const scheduler = new Scheduler({
+		clock: systemClock,
+		onChange: refreshUI,
+		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: ScheduleAction; 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.action === "clear") {
+			const count = scheduler.clear();
+			return count === 0 ? "No active schedules to clear." : `Cleared ${count} schedule${count === 1 ? "" : "s"}. Already queued prompts cannot be withdrawn.`;
+		}
+		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;
+		refreshUI();
+	});
+	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(WIDGET_KEY, undefined);
+			if (ctx.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, undefined);
+		}
+		mountedWidget = 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, cancel for one schedule, and clear for all schedules. 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, cancel, or clear 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,173 @@
+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(): number {
+		const count = this.schedules.size;
+		for (const schedule of this.schedules.values()) {
+			if (schedule.timer !== undefined) this.clock.clearTimeout(schedule.timer);
+		}
+		this.schedules.clear();
+		if (count > 0) this.onChange();
+		return count;
+	}
+
+	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,70 @@
+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);
+const firstClear = scheduler.add("1h", "Check build");
+const secondClear = scheduler.add("2h", "Check deployment");
+assert.notEqual(firstClear.id, secondClear.id);
+assert.equal(clock.timers.size, 2);
+assert.equal(scheduler.clear(), 2);
+assert.equal(clock.timers.size, 0, "clear cancels every timer");
+assert.equal(scheduler.clear(), 0);
+assert.ok(changes >= 5);
+console.log("Scheduler core tests passed");

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

@@ -0,0 +1,117 @@
+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 widgets = new Map([["herdr-subagents", { render: () => ["Herdr Fleet"] }]]);
+const widgetOptions = new Map([["herdr-subagents", { placement: "belowEditor" }]]);
+let renderRequests = 0;
+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,
+	mode: "tui",
+	ui: {
+		setStatus(key, value) { if (value === undefined) statuses.delete(key); else statuses.set(key, value); },
+		setWidget(key, value, options) {
+			if (value === undefined) {
+				widgets.delete(key);
+				widgetOptions.delete(key);
+			} else {
+				widgets.set(key, value({ requestRender() { renderRequests += 1; } }, { fg(_color, text) { return text; } }));
+				widgetOptions.set(key, options);
+			}
+		},
+		notify(message, level) { notifications.push({ message, level }); },
+	},
+};
+await handlers.get("session_start")({}, context);
+assert.ok(tool);
+assert.ok(commands.has("schedule"));
+assert.deepEqual(tool.parameters.properties.action.enum, ["add", "list", "trigger", "cancel", "clear"]);
+
+const add = await tool.execute("add", { action: "add", every: "1h", prompt: "Check CI" });
+assert.match(add.content[0].text, /Created schedule-1/);
+assert.equal(statuses.has("scheduler"), false, "scheduler no longer competes for footer status space");
+assert.deepEqual(widgetOptions.get("scheduler"), { placement: "aboveEditor" });
+assert.deepEqual(widgetOptions.get("herdr-subagents"), { placement: "belowEditor" });
+assert.match(widgets.get("scheduler").render(100).join("\n"), /1 active schedule/);
+assert.match(widgets.get("scheduler").render(100).join("\n"), /schedule-1 · 1h · next/);
+assert.ok(widgets.has("herdr-subagents"), "Scheduler mounting preserves the Herdr Fleet widget");
+
+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);
+assert.equal(widgets.has("scheduler"), false, "removing the final schedule removes the multi-line widget");
+assert.ok(widgets.has("herdr-subagents"), "Scheduler cleanup preserves the Herdr Fleet widget");
+await tool.execute("clear-add-one", { action: "add", every: "2h", prompt: "Check deployment" });
+await tool.execute("clear-add-two", { action: "add", every: "3h", prompt: "Check release" });
+assert.match(widgets.get("scheduler").render(100).join("\n"), /2 active schedules/);
+assert.match(widgets.get("scheduler").render(100).join("\n"), /schedule-2/);
+assert.match(widgets.get("scheduler").render(100).join("\n"), /schedule-3/);
+await commands.get("schedule").handler("clear", context);
+assert.match(notifications.at(-1).message, /Cleared 2 schedules/);
+assert.equal(timers.size, 0, "clear cancels every active timer");
+assert.equal(widgets.has("scheduler"), false, "clear removes the widget");
+assert.ok(widgets.has("herdr-subagents"), "clear does not remove Herdr Fleet");
+const emptyClear = await tool.execute("empty-clear", { action: "clear" });
+assert.equal(emptyClear.content[0].text, "No active schedules to clear.");
+await tool.execute("shutdown-add", { action: "add", every: "4h", prompt: "Check shutdown" });
+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");
+assert.equal(widgets.has("scheduler"), false);
+assert.ok(widgets.has("herdr-subagents"), "Scheduler shutdown does not remove Herdr Fleet");
+assert.ok(renderRequests >= 4, "schedule changes request widget rerenders");
+globalThis.setTimeout = originalSetTimeout;
+globalThis.clearTimeout = originalClearTimeout;
+console.log("Scheduler extension integration tests passed");