@jl1990/pi-scheduler 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jl1990
+
+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

@@ -0,0 +1,189 @@
+# Pi Scheduler
+
+**Give Pi coding agents a clock: schedule reminders, shell commands, and self-waking prompts for CI polling and autonomous follow-ups.**
+
+Pi Scheduler is a [Pi](https://github.com/earendil-works/pi) extension that lets an agent schedule future work from inside the conversation. Use it for simple reminders, delayed shell commands, or autonomous workflows where the agent needs to wake itself up later, check an external system, and continue.
+
+## Why?
+
+Coding agents often need to wait:
+
+- A GitLab/GitHub pipeline is still running.
+- A deployment needs a few minutes to roll out.
+- A long build or test command should be checked later.
+- You want the agent to remind you or continue a task after a delay.
+
+Without scheduling, the agent has to stop and hope you come back. With Pi Scheduler, it can schedule its own follow-up prompt:
+
+> “Check the pipeline again in 3 minutes. If it failed, inspect logs and fix it. If it is still running, schedule another check.”
+
+## Features
+
+- **Self-waking prompts** — schedule a future prompt that wakes the agent in the current Pi session.
+- **Delayed shell commands** — run commands later with optional follow-up prompts containing stdout/stderr.
+- **Reminders and messages** — notify the user or inject scheduled messages.
+- **Agent-callable tools** — the LLM can schedule, list, and cancel tasks itself.
+- **Slash commands** — manually schedule tasks from the Pi prompt.
+- **Persistent state** — scheduled tasks are stored in `~/.pi/agent/state/scheduler/tasks.json`.
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:@jl1990/pi-scheduler
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:git@github.com:jl1990/pi-scheduler.git
+```
+
+Then restart Pi, or run:
+
+```text
+/reload
+```
+
+## Agent tools
+
+Pi Scheduler registers these tools for the agent:
+
+- `schedule_task` — schedule a future action.
+- `list_scheduled_tasks` — list pending or historical tasks.
+- `cancel_scheduled_task` — cancel a pending task by ID or prefix.
+
+### Scheduled action types
+
+| Action | What it does | Best for |
+| --- | --- | --- |
+| `prompt` | Injects a future user prompt and wakes the agent | CI polling, deployments, autonomous follow-ups |
+| `shell` | Runs a future shell command | Delayed checks, tests, status commands |
+| `notify` | Shows a reminder/notification | Human reminders |
+| `message` | Injects a scheduled custom message | Lightweight status/context messages |
+
+## Example: autonomous GitLab pipeline polling
+
+Ask the agent to create a pipeline, then schedule itself to check it:
+
+```json
+{
+  "action": "prompt",
+  "when": "3m",
+  "prompt": "Check GitLab pipeline 123 for project jl1990/example. If it passed, report success. If it failed, inspect the failed job logs and propose or apply fixes. If it is still running, schedule another check in 3 minutes."
+}
+```
+
+This pattern lets the agent keep working without you manually nudging it every few minutes.
+
+## Example: run a command later, then wake the agent
+
+```json
+{
+  "action": "shell",
+  "when": "2m",
+  "command": "glab pipeline view 123 --repo jl1990/example",
+  "followUpPrompt": "Review this pipeline status. If it is still running, schedule another check. If it failed, inspect logs and fix the issue."
+}
+```
+
+When the command finishes, Pi Scheduler sends the command output back to the agent together with your follow-up instruction.
+
+## Slash commands
+
+```text
+/schedule [notify|prompt|shell|message] <when> :: <payload>
+/remind <when> <message>
+/schedules
+/schedules all
+/schedule-cancel <id-or-prefix>
+```
+
+Examples:
+
+```text
+/remind 5m stretch
+/schedule prompt 3m :: Check the GitLab pipeline and schedule another check if still running.
+/schedule shell at 14:30 :: npm test
+/schedules
+/schedule-cancel task_abc123
+```
+
+## Time formats
+
+Supported examples:
+
+```text
+5m
+in 10 minutes
+1h30m
+2 days
+tomorrow at 9am
+14:30
+2026-07-06T10:00:00
+```
+
+## Important limitations
+
+Pi Scheduler currently uses **in-process timers**:
+
+- If Pi is running, tasks fire at the scheduled time.
+- If Pi is closed, tasks do not fire while Pi is closed.
+- Pending/missed tasks are loaded again when the relevant Pi session starts, and due tasks fire then.
+
+This is enough for live agent workflows like CI polling while a Pi session is open. A future version could add OS-level `cron`, `at`, launchd, systemd, or a small daemon for exact wakeups while Pi is not running.
+
+## Development
+
+Run tests:
+
+```bash
+npm test
+```
+
+Check what will be published to npm:
+
+```bash
+npm pack --dry-run
+```
+
+Load-check the extension locally:
+
+```bash
+PI_OFFLINE=1 pi --no-extensions -e ./extensions/scheduler/index.ts --list-models __unlikely_model_filter__
+```
+
+Try a command without starting a model turn:
+
+```bash
+PI_OFFLINE=1 pi --no-extensions -e ./extensions/scheduler/index.ts --no-session --mode json -p "/schedules"
+```
+
+## Publishing
+
+This package is published as:
+
+```text
+@jl1990/pi-scheduler
+```
+
+The GitHub Actions workflow `.github/workflows/publish-npm.yml` publishes to npm when a GitHub Release is published. It also supports manual runs from the Actions tab, including a dry-run option.
+
+Before the first automated publish, configure one of these npm auth methods:
+
+1. **Trusted publishing** on npm, for repository `jl1990/pi-scheduler` and workflow `publish-npm.yml`.
+2. Or a GitHub repository secret named `NPM_TOKEN` with publish permission.
+
+Release flow:
+
+```bash
+npm version patch   # or minor/major
+git push --follow-tags
+```
+
+Then create/publish a GitHub Release for the new tag. The workflow will run tests, check package contents, and publish with npm provenance.
+
+## Security notes
+
+This extension can run scheduled shell commands with your local user permissions. Only install Pi packages from sources you trust, and review scheduled shell tasks before using them in sensitive environments.

package/extensions/scheduler/index.ts

@@ -0,0 +1,463 @@
+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 { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { Type } from "typebox";
+
+// Keep the scheduler logic testable from plain node --test.
+const core = require("./scheduler-core.cjs");
+
+const ACTIONS = ["notify", "prompt", "shell", "message"] as const;
+const STATE_FILE = join(homedir(), ".pi", "agent", "state", "scheduler", "tasks.json");
+const MAX_TIMER_DELAY_MS = 2_147_483_647; // setTimeout's practical max (~24.8 days)
+const DEFAULT_SHELL_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_STORED_OUTPUT_CHARS = 12_000;
+const MAX_PROMPT_OUTPUT_CHARS = 18_000;
+
+type ScheduledTask = Record<string, any>;
+
+function truncateMiddle(text: string | undefined, maxChars: number): string {
+	const value = text ?? "";
+	if (value.length <= maxChars) return value;
+	const head = Math.floor(maxChars * 0.35);
+	const tail = maxChars - head - 80;
+	return `${value.slice(0, head)}\n\n[... truncated ${value.length - maxChars} characters ...]\n\n${value.slice(-tail)}`;
+}
+
+function currentSessionFile(ctx: ExtensionContext): string | undefined {
+	return ctx.sessionManager.getSessionFile() ?? undefined;
+}
+
+function taskBelongsToSession(task: ScheduledTask, ctx: ExtensionContext): boolean {
+	const sessionFile = currentSessionFile(ctx);
+	return !task.sessionFile || !sessionFile || task.sessionFile === sessionFile;
+}
+
+function sendAgentPrompt(pi: ExtensionAPI, ctx: ExtensionContext, prompt: string): void {
+	if (ctx.isIdle()) {
+		pi.sendUserMessage(prompt);
+	} else {
+		pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+	}
+}
+
+function scheduledPromptHeader(task: ScheduledTask): string {
+	return [
+		`[Scheduled task ${task.id} fired]`,
+		`Action: ${task.action}`,
+		`Scheduled for: ${task.dueAt}`,
+		"",
+	].join("\n");
+}
+
+function taskCreatedText(task: ScheduledTask): string {
+	return `Scheduled ${task.action} task ${task.id} for ${new Date(task.dueAt).toLocaleString()}: ${core.taskSummary(task)}`;
+}
+
+function shellResultPrompt(task: ScheduledTask, result: Record<string, any>): string {
+	const stdout = truncateMiddle(result.stdout ?? "", MAX_PROMPT_OUTPUT_CHARS);
+	const stderr = truncateMiddle(result.stderr ?? "", MAX_PROMPT_OUTPUT_CHARS);
+	return [
+		scheduledPromptHeader(task).trimEnd(),
+		"A scheduled shell command completed.",
+		"",
+		`Command: ${task.command}`,
+		`CWD: ${result.cwd}`,
+		`Exit code: ${result.code}`,
+		`Timed out/killed: ${Boolean(result.killed)}`,
+		"",
+		"STDOUT:",
+		"```",
+		stdout,
+		"```",
+		"",
+		"STDERR:",
+		"```",
+		stderr,
+		"```",
+		"",
+		"Follow-up instruction:",
+		task.followUpPrompt,
+	].join("\n");
+}
+
+export default function schedulerExtension(pi: ExtensionAPI) {
+	let tasks: ScheduledTask[] = [];
+	let timers = new Map<string, NodeJS.Timeout>();
+	let activeCtx: ExtensionContext | undefined;
+	let saveQueue: Promise<void> = Promise.resolve();
+	const firing = new Set<string>();
+
+	async function loadTasks(): Promise<void> {
+		try {
+			const raw = await readFile(STATE_FILE, "utf8");
+			const parsed = JSON.parse(raw);
+			tasks = core.sanitizeTasks(parsed.tasks ?? parsed);
+		} catch (error: any) {
+			if (error?.code === "ENOENT") {
+				tasks = [];
+				return;
+			}
+			throw error;
+		}
+	}
+
+	async function saveTasks(): Promise<void> {
+		const payload = JSON.stringify({ version: 1, updatedAt: new Date().toISOString(), tasks }, null, 2) + "\n";
+		saveQueue = saveQueue.then(async () => {
+			await mkdir(dirname(STATE_FILE), { recursive: true });
+			const tmp = `${STATE_FILE}.${process.pid}.tmp`;
+			await writeFile(tmp, payload, "utf8");
+			await rename(tmp, STATE_FILE);
+		});
+		return saveQueue;
+	}
+
+	function clearTimers(): void {
+		for (const timer of timers.values()) clearTimeout(timer);
+		timers = new Map();
+	}
+
+	function updateStatus(ctx = activeCtx): void {
+		if (!ctx?.hasUI) return;
+		const count = core.pendingTasks(tasks).filter((task: ScheduledTask) => taskBelongsToSession(task, ctx)).length;
+		ctx.ui.setStatus("scheduler", count ? `⏰ ${count} scheduled` : undefined);
+	}
+
+	function scheduleTaskTimer(task: ScheduledTask, ctx: ExtensionContext): void {
+		if (task.status !== "pending") return;
+		if (!taskBelongsToSession(task, ctx)) return;
+
+		const dueAt = Date.parse(task.dueAt);
+		if (!Number.isFinite(dueAt)) return;
+		const delay = Math.max(0, dueAt - Date.now());
+		const timerDelay = Math.min(delay, MAX_TIMER_DELAY_MS);
+
+		const timer = setTimeout(() => {
+			timers.delete(task.id);
+			if (Date.now() < dueAt) {
+				scheduleTaskTimer(task, ctx);
+				return;
+			}
+			void fireTask(task.id, ctx);
+		}, timerDelay);
+		timers.set(task.id, timer);
+	}
+
+	function rescheduleAll(ctx = activeCtx): void {
+		if (!ctx) return;
+		clearTimers();
+		for (const task of core.pendingTasks(tasks)) {
+			scheduleTaskTimer(task, ctx);
+		}
+		updateStatus(ctx);
+	}
+
+	function recordMessage(content: string, details?: Record<string, any>, triggerTurn = false): void {
+		pi.sendMessage(
+			{
+				customType: "scheduled-task",
+				content,
+				display: true,
+				details,
+			},
+			{ triggerTurn },
+		);
+	}
+
+	async function executeTask(task: ScheduledTask, ctx: ExtensionContext): Promise<Record<string, any>> {
+		if (task.action === "notify") {
+			const message = task.message ?? "Scheduled reminder";
+			if (ctx.hasUI) ctx.ui.notify(message, "info");
+			recordMessage(`🔔 ${message}`, { task }, false);
+			return { delivered: "notify" };
+		}
+
+		if (task.action === "prompt") {
+			const prompt = `${scheduledPromptHeader(task)}${task.prompt}`;
+			sendAgentPrompt(pi, ctx, prompt);
+			return { delivered: "prompt" };
+		}
+
+		if (task.action === "message") {
+			const message = task.message ?? "Scheduled message";
+			recordMessage(`⏰ ${message}`, { task }, task.triggerTurn !== false);
+			return { delivered: "message", triggerTurn: task.triggerTurn !== false };
+		}
+
+		if (task.action === "shell") {
+			const cwd = task.cwd || ctx.cwd;
+			const timeout = task.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+			if (ctx.hasUI) ctx.ui.notify(`Running scheduled command: ${task.command}`, "info");
+
+			const result = await pi.exec("bash", ["-lc", task.command], { cwd, timeout });
+			const shellResult = {
+				command: task.command,
+				cwd,
+				timeoutMs: timeout,
+				code: result.code,
+				killed: result.killed,
+				stdout: truncateMiddle(result.stdout ?? "", MAX_STORED_OUTPUT_CHARS),
+				stderr: truncateMiddle(result.stderr ?? "", MAX_STORED_OUTPUT_CHARS),
+			};
+
+			recordMessage(
+				`🖥️ Scheduled command ${task.id} finished with exit code ${result.code}: ${task.command}`,
+				{ task, result: shellResult },
+				false,
+			);
+
+			if (task.followUpPrompt) {
+				sendAgentPrompt(pi, ctx, shellResultPrompt(task, shellResult));
+			}
+
+			return shellResult;
+		}
+
+		throw new Error(`Unsupported scheduled action: ${task.action}`);
+	}
+
+	async function fireTask(taskId: string, ctx: ExtensionContext): Promise<void> {
+		const task = tasks.find((candidate) => candidate.id === taskId);
+		if (!task || task.status !== "pending" || firing.has(task.id)) return;
+		if (!taskBelongsToSession(task, ctx)) return;
+
+		firing.add(task.id);
+		try {
+			core.markScheduledTaskRunning(tasks, task.id, new Date());
+			await saveTasks();
+			const result = await executeTask(task, ctx);
+			core.markScheduledTaskFired(tasks, task.id, new Date(), result);
+			await saveTasks();
+		} catch (error: any) {
+			core.markScheduledTaskFailed(tasks, task.id, new Date(), error);
+			await saveTasks();
+			const message = `Scheduled task ${task.id} failed: ${error?.message ?? String(error)}`;
+			if (ctx.hasUI) ctx.ui.notify(message, "error");
+			recordMessage(`⚠️ ${message}`, { task, error: error?.message ?? String(error) }, false);
+		} finally {
+			firing.delete(task.id);
+			rescheduleAll(ctx);
+		}
+	}
+
+	async function createAndSchedule(input: Record<string, any>, ctx: ExtensionContext): Promise<ScheduledTask> {
+		const task = core.createScheduledTask(
+			{
+				...input,
+				whenText: input.whenText ?? input.when,
+				cwd: input.cwd ?? ctx.cwd,
+				sessionFile: currentSessionFile(ctx),
+			},
+			new Date(),
+		);
+		tasks.push(task);
+		await saveTasks();
+		rescheduleAll(ctx);
+		return task;
+	}
+
+	function parseCommandTask(args: string, ctx: ExtensionContext): Record<string, any> {
+		const parsed = core.splitScheduleCommand(args, new Date());
+		const base: Record<string, any> = { action: parsed.action, whenText: parsed.whenText, cwd: ctx.cwd };
+		if (parsed.action === "prompt") return { ...base, prompt: parsed.payload };
+		if (parsed.action === "shell") return { ...base, command: parsed.payload };
+		return { ...base, message: parsed.payload };
+	}
+
+	pi.registerMessageRenderer("scheduled-task", (message, options, theme) => {
+		let text = `${theme.fg("accent", theme.bold("scheduled"))} ${message.content}`;
+		if (options.expanded && message.details) {
+			text += `\n${theme.fg("dim", JSON.stringify(message.details, null, 2))}`;
+		}
+		return new Text(text, 0, 0);
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		activeCtx = ctx;
+		await loadTasks();
+		rescheduleAll(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		clearTimers();
+		if (ctx.hasUI) ctx.ui.setStatus("scheduler", undefined);
+		activeCtx = undefined;
+	});
+
+	pi.registerCommand("schedule", {
+		description: "Schedule a notify, prompt, shell command, or message action",
+		handler: async (args, ctx) => {
+			if (!args.trim()) {
+				ctx.ui.notify("Usage: /schedule [notify|prompt|shell|message] <when> :: <payload>", "warning");
+				return;
+			}
+			try {
+				const task = await createAndSchedule(parseCommandTask(args, ctx), ctx);
+				ctx.ui.notify(taskCreatedText(task), "info");
+				recordMessage(taskCreatedText(task), { task }, false);
+			} catch (error: any) {
+				ctx.ui.notify(error?.message ?? String(error), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("remind", {
+		description: "Alias for /schedule notify",
+		handler: async (args, ctx) => {
+			if (!args.trim()) {
+				ctx.ui.notify("Usage: /remind <when> <message>", "warning");
+				return;
+			}
+			try {
+				const parsed = core.splitScheduleCommand(`notify ${args}`, new Date());
+				const task = await createAndSchedule(
+					{ action: "notify", whenText: parsed.whenText, message: parsed.payload, cwd: ctx.cwd },
+					ctx,
+				);
+				ctx.ui.notify(taskCreatedText(task), "info");
+				recordMessage(taskCreatedText(task), { task }, false);
+			} catch (error: any) {
+				ctx.ui.notify(error?.message ?? String(error), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("schedules", {
+		description: "List scheduled tasks; pass 'all' to include fired/cancelled/failed tasks",
+		handler: async (args, ctx) => {
+			await loadTasks();
+			const includeAll = args.trim().toLowerCase() === "all";
+			const visible = tasks.filter((task) => taskBelongsToSession(task, ctx));
+			recordMessage(core.formatTaskList(visible, new Date(), { includeAll }), { includeAll, tasks: visible }, false);
+			updateStatus(ctx);
+		},
+	});
+
+	pi.registerCommand("schedule-cancel", {
+		description: "Cancel a pending scheduled task by id or id prefix",
+		handler: async (args, ctx) => {
+			const id = args.trim();
+			if (!id) {
+				ctx.ui.notify("Usage: /schedule-cancel <id>", "warning");
+				return;
+			}
+			try {
+				await loadTasks();
+				const visible = tasks.filter((task) => taskBelongsToSession(task, ctx));
+				const task = core.cancelScheduledTask(visible, id, new Date());
+				await saveTasks();
+				rescheduleAll(ctx);
+				ctx.ui.notify(`Cancelled scheduled task ${task.id}`, "info");
+				recordMessage(`Cancelled scheduled task ${task.id}`, { task }, false);
+			} catch (error: any) {
+				ctx.ui.notify(error?.message ?? String(error), "error");
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "schedule_task",
+		label: "Schedule Task",
+		description:
+			"Schedule a future action in this Pi session: notify the user, wake the agent with a prompt, run a shell command, or send a custom message.",
+		promptSnippet: "Schedule future notify, prompt, shell, or message actions in the current Pi session",
+		promptGuidelines: [
+			"Use schedule_task when the user asks to do something later, when waiting on external systems such as CI/CD pipelines, or when the agent needs to wake itself up to continue work.",
+			"Prefer schedule_task action='prompt' for agentic follow-ups; include enough context for the future agent to know what to check and what to do next.",
+			"For polling workflows, schedule a future prompt that says to check the status and schedule another check if the work is still pending.",
+			"Use schedule_task action='shell' with followUpPrompt when a fixed command should run later and its output should be reviewed by the agent.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(ACTIONS, {
+				description: "What to do at the scheduled time. Use prompt to wake the agent.",
+				default: "prompt",
+			}),
+			when: Type.String({
+				description: "When to run, e.g. '5m', 'in 10 minutes', 'tomorrow at 9am', '14:30', or an ISO datetime.",
+			}),
+			message: Type.Optional(Type.String({ description: "Message for notify/message actions." })),
+			prompt: Type.Optional(Type.String({ description: "User prompt to inject for prompt actions." })),
+			command: Type.Optional(Type.String({ description: "Shell command to run for shell actions." })),
+			payload: Type.Optional(Type.String({ description: "Generic payload fallback for any action." })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for shell actions; defaults to current cwd." })),
+			timeoutMs: Type.Optional(Type.Number({ description: "Shell timeout in milliseconds.", minimum: 1000 })),
+			followUpPrompt: Type.Optional(
+				Type.String({
+					description:
+						"For shell actions: if set, wake the agent after the command completes and include stdout/stderr plus this instruction.",
+				}),
+			),
+			title: Type.Optional(Type.String({ description: "Optional human-readable title." })),
+			triggerTurn: Type.Optional(
+				Type.Boolean({ description: "For message actions: whether the message should trigger an agent turn. Default true." }),
+			),
+		}),
+		prepareArguments(args) {
+			if (!args || typeof args !== "object") return args;
+			const input = args as Record<string, any>;
+			if (input.when === undefined && typeof input.whenText === "string") {
+				return { ...input, when: input.whenText };
+			}
+			return args;
+		},
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const task = await createAndSchedule(params, ctx);
+			return {
+				content: [{ type: "text", text: taskCreatedText(task) }],
+				details: { task, pending: core.pendingTasks(tasks) },
+			};
+		},
+		renderCall(args, theme) {
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("schedule_task"))} ${theme.fg("muted", args.action ?? "prompt")} ${theme.fg("accent", args.when ?? "")}`,
+				0,
+				0,
+			);
+		},
+		renderResult(result, _options, theme) {
+			const text = result.content?.[0];
+			return new Text(theme.fg("success", "✓ ") + (text?.type === "text" ? text.text : "Scheduled"), 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "list_scheduled_tasks",
+		label: "List Scheduled Tasks",
+		description: "List pending or all scheduled tasks for the current Pi session.",
+		promptSnippet: "List pending/all scheduled future actions in the current Pi session",
+		parameters: Type.Object({
+			includeAll: Type.Optional(Type.Boolean({ description: "Include fired, cancelled, and failed tasks. Default false." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			await loadTasks();
+			const visible = tasks.filter((task) => taskBelongsToSession(task, ctx));
+			const text = core.formatTaskList(visible, new Date(), { includeAll: Boolean(params.includeAll) });
+			updateStatus(ctx);
+			return { content: [{ type: "text", text }], details: { tasks: visible } };
+		},
+	});
+
+	pi.registerTool({
+		name: "cancel_scheduled_task",
+		label: "Cancel Scheduled Task",
+		description: "Cancel a pending scheduled task by id or id prefix.",
+		promptSnippet: "Cancel a pending scheduled task by id or prefix",
+		parameters: Type.Object({
+			id: Type.String({ description: "Task id or unique id prefix." }),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			await loadTasks();
+			const visible = tasks.filter((task) => taskBelongsToSession(task, ctx));
+			const task = core.cancelScheduledTask(visible, params.id, new Date());
+			await saveTasks();
+			rescheduleAll(ctx);
+			return {
+				content: [{ type: "text", text: `Cancelled scheduled task ${task.id}` }],
+				details: { task, pending: core.pendingTasks(tasks) },
+			};
+		},
+	});
+}

package/extensions/scheduler/scheduler-core.cjs

@@ -0,0 +1,388 @@
+const VALID_ACTIONS = new Set(["notify", "prompt", "shell", "message"]);
+const VALID_STATUSES = new Set(["pending", "running", "fired", "cancelled", "failed"]);
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+
+function asDate(value) {
+	const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+	if (Number.isNaN(date.getTime())) throw new Error(`Invalid date: ${value}`);
+	return date;
+}
+
+function compactSpaces(text) {
+	return String(text ?? "").trim().replace(/\s+/g, " ");
+}
+
+function unitToMs(unit) {
+	const u = unit.toLowerCase();
+	if (u === "s" || u.startsWith("sec")) return SECOND;
+	if (u === "m" || u.startsWith("min")) return MINUTE;
+	if (u === "h" || u.startsWith("hr") || u.startsWith("hour")) return HOUR;
+	if (u === "d" || u.startsWith("day")) return DAY;
+	if (u === "w" || u.startsWith("week")) return WEEK;
+	return undefined;
+}
+
+function parseDurationMs(text) {
+	let input = compactSpaces(text).toLowerCase();
+	if (!input) return null;
+	input = input.replace(/^in\s+/, "").replace(/,/g, " ").replace(/\band\b/g, " ").replace(/\s+/g, " ").trim();
+	if (!input) return null;
+
+	const re = /(\d+(?:\.\d+)?)\s*(weeks?|w|days?|d|hours?|hrs?|hr|h|minutes?|mins?|min|m|seconds?|secs?|sec|s)/gi;
+	let total = 0;
+	let matched = false;
+	let cursor = 0;
+	let match;
+
+	while ((match = re.exec(input)) !== null) {
+		const between = input.slice(cursor, match.index);
+		if (between.trim() !== "") return null;
+		const value = Number(match[1]);
+		const unitMs = unitToMs(match[2]);
+		if (!Number.isFinite(value) || value <= 0 || !unitMs) return null;
+		total += value * unitMs;
+		matched = true;
+		cursor = re.lastIndex;
+	}
+
+	if (!matched || input.slice(cursor).trim() !== "") return null;
+	return Math.round(total);
+}
+
+function parseTimeToken(text, options = {}) {
+	const input = compactSpaces(text).toLowerCase();
+	const match = input.match(/^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i);
+	if (!match) return null;
+
+	const hasColon = match[2] !== undefined;
+	const suffix = match[3]?.toLowerCase();
+	if (!hasColon && !suffix && !options.allowBareHour) return null;
+
+	let hour = Number(match[1]);
+	const minute = match[2] === undefined ? 0 : Number(match[2]);
+	if (!Number.isInteger(minute) || minute < 0 || minute > 59) return null;
+
+	if (suffix) {
+		if (hour < 1 || hour > 12) return null;
+		if (suffix === "am") hour = hour === 12 ? 0 : hour;
+		if (suffix === "pm") hour = hour === 12 ? 12 : hour + 12;
+	} else {
+		if (hour < 0 || hour > 23) return null;
+	}
+
+	return { hour, minute };
+}
+
+function parseClockExpression(text, now) {
+	let input = compactSpaces(text).toLowerCase();
+	if (!input) return null;
+
+	let dayOffset;
+	let hadAt = false;
+
+	if (input === "tomorrow") return now.getTime() + DAY;
+	if (input === "today") return now.getTime();
+
+	if (input.startsWith("tomorrow ")) {
+		dayOffset = 1;
+		input = input.slice("tomorrow".length).trim();
+	} else if (input.startsWith("today ")) {
+		dayOffset = 0;
+		input = input.slice("today".length).trim();
+	}
+
+	if (input.startsWith("at ")) {
+		hadAt = true;
+		input = input.slice(3).trim();
+	}
+
+	if (!input) return null;
+	const parsed = parseTimeToken(input, { allowBareHour: hadAt || dayOffset !== undefined });
+	if (!parsed) return null;
+
+	const target = new Date(now.getTime());
+	if (dayOffset !== undefined) target.setDate(target.getDate() + dayOffset);
+	target.setHours(parsed.hour, parsed.minute, 0, 0);
+
+	if (dayOffset === undefined && target.getTime() <= now.getTime()) target.setDate(target.getDate() + 1);
+	return target.getTime();
+}
+
+function parseWhen(text, nowValue = new Date()) {
+	const now = asDate(nowValue);
+	const input = compactSpaces(text);
+	if (!input) throw new Error("Scheduled time is required");
+
+	const durationMs = parseDurationMs(input);
+	if (durationMs !== null) {
+		return { dueAtMs: now.getTime() + durationMs, kind: "relative", normalized: input };
+	}
+
+	const clockMs = parseClockExpression(input, now);
+	if (clockMs !== null) {
+		if (clockMs <= now.getTime()) throw new Error(`Scheduled time is in the past: ${input}`);
+		return { dueAtMs: clockMs, kind: "clock", normalized: input };
+	}
+
+	const absoluteMs = Date.parse(input);
+	if (!Number.isNaN(absoluteMs)) {
+		if (absoluteMs <= now.getTime()) throw new Error(`Scheduled time is in the past: ${input}`);
+		return { dueAtMs: absoluteMs, kind: "absolute", normalized: input };
+	}
+
+	throw new Error(`Could not parse scheduled time: ${input}`);
+}
+
+function normalizeAction(action) {
+	const value = compactSpaces(action || "notify").toLowerCase();
+	if (!VALID_ACTIONS.has(value)) throw new Error(`Invalid scheduled action: ${value}`);
+	return value;
+}
+
+function splitScheduleCommand(args, nowValue = new Date()) {
+	const text = compactSpaces(args);
+	if (!text) throw new Error("Usage: /schedule [notify|prompt|shell|message] <when> <payload>");
+
+	const separatorIndex = text.indexOf("::");
+	if (separatorIndex >= 0) {
+		const left = compactSpaces(text.slice(0, separatorIndex));
+		const payload = compactSpaces(text.slice(separatorIndex + 2));
+		if (!left || !payload) throw new Error("Usage with separator: /schedule [action] <when> :: <payload>");
+		const leftTokens = left.split(" ");
+		let action = "notify";
+		let whenText = left;
+		if (VALID_ACTIONS.has(leftTokens[0].toLowerCase())) {
+			action = leftTokens[0].toLowerCase();
+			whenText = compactSpaces(leftTokens.slice(1).join(" "));
+		}
+		parseWhen(whenText, nowValue);
+		return { action, whenText, payload };
+	}
+
+	const tokens = text.split(" ");
+	let action = "notify";
+	let restTokens = tokens;
+	if (VALID_ACTIONS.has(tokens[0].toLowerCase())) {
+		action = tokens[0].toLowerCase();
+		restTokens = tokens.slice(1);
+	}
+
+	const maxPrefix = Math.min(restTokens.length - 1, 10);
+	let bestMatch = null;
+	for (let i = 1; i <= maxPrefix; i++) {
+		const whenText = restTokens.slice(0, i).join(" ");
+		const payload = restTokens.slice(i).join(" ").trim();
+		if (!payload) continue;
+		try {
+			parseWhen(whenText, nowValue);
+			bestMatch = { action, whenText, payload };
+		} catch {
+			// Try a longer prefix.
+		}
+	}
+	if (bestMatch) return bestMatch;
+
+	throw new Error("Could not split scheduled task. Try: /schedule prompt 5m summarize progress");
+}
+
+function generateId(nowValue = new Date()) {
+	const now = asDate(nowValue);
+	return `task_${now.getTime().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function validateTimeoutMs(value) {
+	if (value === undefined || value === null) return undefined;
+	const n = Number(value);
+	if (!Number.isFinite(n) || n <= 0) throw new Error("timeoutMs must be a positive number");
+	return Math.round(n);
+}
+
+function createScheduledTask(input, nowValue = new Date(), idFn = generateId) {
+	const now = asDate(nowValue);
+	const action = normalizeAction(input.action);
+	const whenText = compactSpaces(input.whenText ?? input.when ?? input.due ?? "");
+	const parsed = parseWhen(whenText, now);
+	const task = {
+		id: idFn(now),
+		action,
+		status: "pending",
+		createdAt: now.toISOString(),
+		dueAt: new Date(parsed.dueAtMs).toISOString(),
+		whenText,
+	};
+
+	const message = compactSpaces(input.message ?? input.payload ?? "");
+	const prompt = compactSpaces(input.prompt ?? input.payload ?? input.message ?? "");
+	const command = compactSpaces(input.command ?? input.payload ?? "");
+
+	if (input.title !== undefined) task.title = compactSpaces(input.title);
+	if (input.cwd) task.cwd = String(input.cwd);
+	if (input.sessionFile) task.sessionFile = String(input.sessionFile);
+
+	if (action === "notify") {
+		if (!message) throw new Error("message is required for notify scheduled tasks");
+		task.message = message;
+	} else if (action === "prompt") {
+		if (!prompt) throw new Error("prompt is required for prompt scheduled tasks");
+		task.prompt = prompt;
+	} else if (action === "shell") {
+		if (!command) throw new Error("command is required for shell scheduled tasks");
+		task.command = command;
+		const timeoutMs = validateTimeoutMs(input.timeoutMs);
+		if (timeoutMs !== undefined) task.timeoutMs = timeoutMs;
+		const followUpPrompt = compactSpaces(input.followUpPrompt ?? "");
+		if (followUpPrompt) task.followUpPrompt = followUpPrompt;
+	} else if (action === "message") {
+		if (!message) throw new Error("message is required for message scheduled tasks");
+		task.message = message;
+		if (input.triggerTurn !== undefined) task.triggerTurn = Boolean(input.triggerTurn);
+	}
+
+	return task;
+}
+
+function taskSummary(task) {
+	const raw = task.command ?? task.prompt ?? task.message ?? "";
+	return raw.length > 100 ? `${raw.slice(0, 97)}...` : raw;
+}
+
+function isTaskShape(task) {
+	if (!task || typeof task !== "object") return false;
+	if (typeof task.id !== "string" || !VALID_ACTIONS.has(task.action)) return false;
+	if (!VALID_STATUSES.has(task.status)) return false;
+	if (Number.isNaN(Date.parse(task.dueAt))) return false;
+	return true;
+}
+
+function sanitizeTasks(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter(isTaskShape);
+}
+
+function pendingTasks(tasks) {
+	return tasks
+		.filter((task) => task.status === "pending")
+		.slice()
+		.sort((a, b) => Date.parse(a.dueAt) - Date.parse(b.dueAt));
+}
+
+function dueTasks(tasks, nowValue = new Date()) {
+	const now = asDate(nowValue).getTime();
+	return pendingTasks(tasks).filter((task) => Date.parse(task.dueAt) <= now);
+}
+
+function findTask(tasks, idOrPrefix) {
+	const id = compactSpaces(idOrPrefix);
+	return tasks.find((task) => task.id === id || task.id.startsWith(id));
+}
+
+function cancelScheduledTask(tasks, idOrPrefix, nowValue = new Date()) {
+	const now = asDate(nowValue);
+	const task = findTask(tasks, idOrPrefix);
+	if (!task) throw new Error(`Scheduled task not found: ${idOrPrefix}`);
+	if (task.status !== "pending") throw new Error(`Scheduled task ${task.id} is already ${task.status}`);
+	task.status = "cancelled";
+	task.cancelledAt = now.toISOString();
+	return task;
+}
+
+function markScheduledTaskRunning(tasks, idOrPrefix, nowValue = new Date()) {
+	const now = asDate(nowValue);
+	const task = findTask(tasks, idOrPrefix);
+	if (!task) throw new Error(`Scheduled task not found: ${idOrPrefix}`);
+	if (task.status !== "pending") return task;
+	task.status = "running";
+	task.startedAt = now.toISOString();
+	return task;
+}
+
+function markScheduledTaskFired(tasks, idOrPrefix, nowValue = new Date(), result) {
+	const now = asDate(nowValue);
+	const task = findTask(tasks, idOrPrefix);
+	if (!task) throw new Error(`Scheduled task not found: ${idOrPrefix}`);
+	if (task.status === "cancelled") return task;
+	task.status = "fired";
+	task.firedAt = now.toISOString();
+	if (result !== undefined) task.result = result;
+	return task;
+}
+
+function markScheduledTaskFailed(tasks, idOrPrefix, nowValue = new Date(), error) {
+	const now = asDate(nowValue);
+	const task = findTask(tasks, idOrPrefix);
+	if (!task) throw new Error(`Scheduled task not found: ${idOrPrefix}`);
+	if (task.status === "cancelled") return task;
+	task.status = "failed";
+	task.failedAt = now.toISOString();
+	task.error = error instanceof Error ? error.message : String(error);
+	return task;
+}
+
+function formatRelativeTime(dueAt, nowValue = new Date()) {
+	const now = asDate(nowValue).getTime();
+	let diff = Date.parse(dueAt) - now;
+	if (!Number.isFinite(diff) || diff <= 0) return "due now";
+
+	const parts = [];
+	const units = [
+		["d", DAY],
+		["h", HOUR],
+		["m", MINUTE],
+		["s", SECOND],
+	];
+	for (const [label, size] of units) {
+		const value = Math.floor(diff / size);
+		if (value > 0) {
+			parts.push(`${value}${label}`);
+			diff -= value * size;
+		}
+		if (parts.length >= 2) break;
+	}
+	return `in ${parts.join(" ") || "<1s"}`;
+}
+
+function formatTaskLine(task, nowValue = new Date()) {
+	const due = new Date(task.dueAt);
+	const status = task.status === "pending" ? formatRelativeTime(task.dueAt, nowValue) : task.status;
+	return `- ${task.id} ${status} (${due.toLocaleString()}) [${task.action}] ${taskSummary(task)}`;
+}
+
+function formatTaskList(tasks, nowValue = new Date(), options = {}) {
+	const list = options.includeAll
+		? tasks.slice().sort((a, b) => Date.parse(a.dueAt) - Date.parse(b.dueAt))
+		: pendingTasks(tasks);
+	if (list.length === 0) return options.includeAll ? "No scheduled tasks." : "No pending scheduled tasks.";
+	const title = options.includeAll ? "Scheduled tasks:" : "Pending scheduled tasks:";
+	return [title, ...list.map((task) => formatTaskLine(task, nowValue))].join("\n");
+}
+
+module.exports = {
+	VALID_ACTIONS,
+	VALID_STATUSES,
+	SECOND,
+	MINUTE,
+	HOUR,
+	DAY,
+	parseDurationMs,
+	parseWhen,
+	splitScheduleCommand,
+	normalizeAction,
+	generateId,
+	createScheduledTask,
+	sanitizeTasks,
+	pendingTasks,
+	dueTasks,
+	cancelScheduledTask,
+	markScheduledTaskRunning,
+	markScheduledTaskFired,
+	markScheduledTaskFailed,
+	formatRelativeTime,
+	formatTaskLine,
+	formatTaskList,
+	taskSummary,
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@jl1990/pi-scheduler",
+  "version": "0.1.0",
+  "description": "Give Pi coding agents a clock: schedule reminders, shell commands, and self-waking prompts for CI polling and autonomous follow-ups.",
+  "author": "jl1990",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jl1990/pi-scheduler.git"
+  },
+  "homepage": "https://github.com/jl1990/pi-scheduler#readme",
+  "bugs": {
+    "url": "https://github.com/jl1990/pi-scheduler/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "coding-agent",
+    "ai-agents",
+    "scheduler",
+    "automation",
+    "reminders",
+    "ci-cd",
+    "developer-tools",
+    "typescript"
+  ],
+  "files": [
+    "extensions/**/*",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/scheduler/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "pack:dry-run": "npm pack --dry-run"
+  }
+}