pi-cc-loop 0.1.1 → 0.3.0

package/loopfile.ts

@@ -0,0 +1,103 @@
+/**
+ * loop.md support, resolved at fire time like Claude Code's `<<loop.md>>`
+ * sentinel.
+ *
+ * Claude Code docs: "Edits to loop.md take effect on the next iteration, so
+ * you can refine the instructions while a loop is running. When no loop.md
+ * exists in either location, the loop falls back to the built-in maintenance
+ * prompt. Keep the file concise: content beyond 25,000 bytes is truncated."
+ *
+ * A bare `/loop` stores the sentinel as its prompt instead of the file's text,
+ * so the model does not have to echo a long prompt back to `schedule_wakeup`,
+ * and each tick reads the file again. The full text goes out on the first
+ * delivery and whenever the file changed; otherwise a short reminder points
+ * back to it.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LOOP_FILE_SENTINEL, MAINTENANCE_PROMPT } from "./prompts.ts";
+
+/** Claude Code truncates loop.md beyond this length. */
+export const LOOP_FILE_MAX_CHARS = 25_000;
+
+const MAINTENANCE_MARKER = "\u0000maintenance";
+
+export function isLoopFileSentinel(prompt: string | undefined): boolean {
+	return prompt?.trim() === LOOP_FILE_SENTINEL;
+}
+
+/** How a job's prompt is shown to the user. */
+export function displayPrompt(prompt: string): string {
+	return isLoopFileSentinel(prompt) ? "/loop (loop.md)" : prompt;
+}
+
+/** Project first, then user level, like Claude Code's .claude/loop.md and ~/.claude/loop.md. */
+export function loopFileCandidates(cwd: string): string[] {
+	return [path.join(cwd, ".pi", "loop.md"), path.join(os.homedir(), ".pi", "loop.md")];
+}
+
+/** The first non-empty loop file, truncated like Claude Code's. */
+export function readLoopFile(cwd: string): { path: string; content: string } | null {
+	for (const candidate of loopFileCandidates(cwd)) {
+		let raw: string;
+		try {
+			raw = fs.readFileSync(candidate, "utf8");
+		} catch {
+			continue;
+		}
+		const content = raw.trim();
+		if (content) return { path: candidate, content: truncate(content) };
+	}
+	return null;
+}
+
+function truncate(content: string): string {
+	if (content.length <= LOOP_FILE_MAX_CHARS) return content;
+	const cut = content.lastIndexOf("\n", LOOP_FILE_MAX_CHARS);
+	return `${content.slice(0, cut > 0 ? cut : LOOP_FILE_MAX_CHARS)}\n> WARNING: loop.md was truncated to ${LOOP_FILE_MAX_CHARS} bytes. Keep the task list concise.`;
+}
+
+export type TickMode = "cron" | "wakeup";
+
+/** Remembers what a session was last given, so unchanged tasks are not resent. */
+export class LoopFileDelivery {
+	private lastDelivered: string | null = null;
+
+	/** Send the full text on the next tick (a new /loop, or after compaction). */
+	reset(): void {
+		this.lastDelivered = null;
+	}
+
+	/** The text of one tick for the loop.md sentinel. */
+	resolve(cwd: string, mode: TickMode): string {
+		const file = readLoopFile(cwd);
+		if (file) {
+			if (this.lastDelivered === file.content) {
+				return (
+					"# /loop tick \u2014 loop.md tasks\n" +
+					"Work the tasks from the loop.md contents established earlier in this conversation. " +
+					"If you cannot find them, treat this as a no-op tick."
+				);
+			}
+			this.lastDelivered = file.content;
+			return [
+				`# /loop tick \u2014 tasks from ${file.path}`,
+				"The user configured a loop-tasks file. Work through the tasks defined below; these are the " +
+					"instructions for this tick and every subsequent tick (the reminder on later fires refers back to this message).",
+				"",
+				file.content,
+			].join("\n");
+		}
+		if (this.lastDelivered === MAINTENANCE_MARKER) {
+			return (
+				"# /loop tick \u2014 maintenance pass\n" +
+				"Run the maintenance pass using the instructions established earlier in this conversation. " +
+				"If you cannot find them, treat this as a no-op tick."
+			);
+		}
+		this.lastDelivered = MAINTENANCE_MARKER;
+		return MAINTENANCE_PROMPT;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cc-loop",
-	"version": "0.1.1",
+	"version": "0.3.0",
 	"description": "Claude Code compatible /loop for the Pi coding agent: cron-scheduled fixed intervals, self-paced chains, and the same dispatch semantics as Claude Code.",
 	"author": "tarnish233",
 	"type": "module",
@@ -22,11 +22,7 @@
 		"url": "https://github.com/tarnish233/pi-cc-loop/issues"
 	},
 	"files": [
-		"index.ts",
-		"cron.ts",
-		"schedule.ts",
-		"render.ts",
-		"config.ts",
+		"*.ts",
 		"README.md",
 		"LICENSE"
 	],

package/prompts.ts

@@ -0,0 +1,257 @@
+/**
+ * Model-facing text for pi-cc-loop: the per-run guidelines, the built-in
+ * maintenance prompt and the tool descriptions.
+ *
+ * The tool descriptions follow Claude Code's (v2.1.302) closely. The
+ * differences are Pi's: lowercase tool names, `.pi/` instead of `.claude/`,
+ * and a provider-neutral note about prompt caching.
+ */
+
+/** A bare `/loop` stores this as its prompt; it expands to loop.md (or the maintenance pass) at fire time. */
+export const LOOP_FILE_SENTINEL = "<<loop.md>>";
+
+/** Claude Code's built-in maintenance prompt, used when there is no loop.md. */
+export const MAINTENANCE_PROMPT = [
+	"You are running a scheduled maintenance pass.",
+	"Work through the following, in order:",
+	"1. Continue any unfinished work from the conversation.",
+	"2. Tend to the current branch's pull request: review comments, failed CI runs, merge conflicts.",
+	"3. Run cleanup passes such as bug hunts or simplification when nothing else is pending.",
+	"Do not start new initiatives outside that scope, and only perform irreversible actions",
+	"(push, delete) that continue something the transcript already authorized.",
+	"If nothing needs doing, say so in one line.",
+].join("\n");
+
+export const PROVENANCE = "[loop tick #{n} \u00b7 scheduled by /loop, not typed by the user]";
+/**
+ * A fixed-interval fire is framed as what it is - a scheduled task, not a
+ * loop iteration. Claude Code does the same: "This turn was started
+ * automatically by a schedule, not typed live by the user. The content below is
+ * the stored prompt of a scheduled task ... Treat it as this session's assigned
+ * task and carry it out." It never calls a cron fire a "loop tick"; that word
+ * belongs to dynamic pacing, where the model has to keep the loop alive. Naming
+ * it "loop" here is what made the model try to reschedule.
+ */
+export const SCHEDULED_TASK_PROVENANCE =
+	"[scheduled task {id} \u00b7 {schedule} \u00b7 started by the schedule, not typed by the user; it fires the next tick on its own, so do not call schedule_wakeup]";
+
+const DELAY_ADVICE = [
+	"- Pick the delay from what you are waiting for. For idle ticks with nothing specific to watch, use 1200-1800s.",
+	"  When actively polling external state nothing notifies you about (a CI run, a deploy), match how fast it changes.",
+	"- Do not poll for work Pi will report anyway (a monitor event, a command you are running): use a long",
+	"  fallback (1200s+) instead.",
+].join("\n");
+
+/**
+ * The rules for a `/loop <prompt>` whose interval the command layer could not
+ * parse. Claude Code's /loop is a skill: the model reads the input and works
+ * the schedule out itself, so an interval written in any language works.
+ */
+/**
+ * The instructions for one `/loop` request. Claude Code's `/loop` is a skill:
+ * the command turns into a user message carrying these rules, and the model
+ * drives CronCreate / CronList / CronDelete / ScheduleWakeup itself. Nothing is
+ * created by code, so the conversation shows what was asked and what was done.
+ */
+const LOOP_FILE_SENTINEL_PLACEHOLDER = "__loop_md_sentinel__";
+
+const LOOP_COMMAND_GUIDELINES = [
+	"This is a `/loop` request from the user: {raw}",
+	"",
+	"## Read the input",
+	"- `[interval] <task>`: an interval was given (\"5m\", \"2h\", \"every 20m\", \"每2分钟\", \"每隔2小时\"). Use the fixed-interval mode below.",
+	"- `<task>` alone: no interval. Use the self-paced mode below and choose each delay yourself.",
+	"- An interval alone, or a bare `/loop`: the tasks come from loop.md (see the last section).",
+	"- `stop [id]` or `status`: see those sections.",
+	"",
+	"## Fixed interval (an interval was given)",
+	"1. Call `cron_create` **once**, `recurring: true`, with a 5-field cron expression in local time and the task **without** the interval wording, so every run does the task instead of scheduling it again.",
+	"   - under a minute rounds up to `* * * * *`; 5 minutes is `*/5 * * * *`; every hour is `0 * * * *`; every day is `0 0 * * *`.",
+	"   - if the interval does not divide its unit cleanly, round to the nearest clean interval and say so.",
+	"2. **Then do the task now** \u2014 do not wait for the first fire.",
+	"3. Confirm briefly: what is scheduled, the cron expression, the cadence, the next run from the tool result, that a recurring job expires after 7 days (it fires once more, then is deleted), the job id, and that `/loop stop <id>` cancels it.",
+	"4. Never call `schedule_wakeup` for this loop: the cron fires its own ticks. Scheduling one would run the task twice.",
+	"",
+	"## Self-paced (no interval)",
+	"1. Do the task now, then write your update for the user.",
+	"2. Then call `schedule_wakeup` with `delaySeconds` (60-3600), a one-sentence `reason`, and `prompt` set to the same `/loop` input verbatim ({quoted}). The turn ends as soon as it returns, so call it last.",
+	"{delayAdvice}",
+	"3. If the next iteration waits on an external event and no monitor is running for it, arm `Monitor` once with `loopPrompt` set to {quoted}; keep `delaySeconds` at 1200-1800 as the fallback heartbeat.",
+	"4. If the task is complete or cannot progress without the user, call `schedule_wakeup` with `stop: true` and say why.",
+	"",
+	"## status and stop",
+	"- `status`: call `cron_list` and report each job's id, cadence, next run and prompt, plus whether it is session-only or durable.",
+	"- `stop`: if the id is unknown, call `cron_list` first; then `cron_delete` for a scheduled job. A self-paced loop is ended with `schedule_wakeup` and `stop: true`.",
+	"",
+	"## Flags",
+	"- `--durable`: pass `durable: true` to `cron_create` so the job survives restarts.",
+	"- `--max N`: pass `maxFires: N`.",
+	"",
+	"## loop.md",
+	"When the request has no task of its own (bare `/loop`, or an interval alone), pass the literal sentinel " + LOOP_FILE_SENTINEL_PLACEHOLDER + " as the prompt: it expands at fire time to `.pi/loop.md`, or to the built-in maintenance pass when there is no loop.md.",
+	"For the run you do right now, read `.pi/loop.md` (or `~/.pi/loop.md`) yourself and do those tasks; the sentinel only expands on later fires.",
+].join("\n");
+
+const LOOP_GUIDELINES = [
+	"A self-paced `/loop` is running. Its prompt is: {prompt}",
+	"After this iteration, decide whether the loop continues:",
+	"- To continue, call the `schedule_wakeup` tool with `delaySeconds` (60-3600), a one-sentence `reason`,",
+	"  and `prompt` set to the same /loop prompt verbatim: {quoted}",
+	"- Write your update for the user before you call `schedule_wakeup`: the turn ends as soon as it returns.",
+	DELAY_ADVICE,
+	"- If the task is complete, or the loop cannot move further without the user, call `schedule_wakeup`",
+	"  with `stop: true` instead and say why.",
+].join("\n");
+
+/**
+ * Fixed-interval loops fire their own next tick, so a wakeup scheduled from
+ * one would run the same prompt twice. Claude Code's tick says the same:
+ * "The recurring cron will fire the next tick automatically — do not call
+ * ScheduleWakeup from this tick."
+ */
+const CRON_TICK_GUIDELINES = [
+	"This is a fixed-interval /loop (job {id}, {schedule}): the schedule fires the next tick on its own.",
+	"Do not call `schedule_wakeup` from this tick — it would run this prompt a second time on a self-paced",
+	"schedule. To cancel the loop, call `cron_delete` with id {id}.",
+].join("\n");
+
+/**
+ * How a self-paced loop uses the Monitor tool, after Claude Code's /loop
+ * skill: arm a monitor only when the next iteration waits on an event, arm it
+ * once, and keep the wakeup as a long fallback heartbeat. A monitor event
+ * does not cancel that heartbeat.
+ */
+const MONITOR_GUIDELINES = [
+	"If the next iteration is gated on an external event (a CI run finishing, a PR comment, a log line) and no",
+	"monitor is already running for it, arm one with the `Monitor` tool and set `loopPrompt` to {quoted}, so the",
+	"event wakes you as soon as it happens. Arm it once: on later iterations call `monitor_list` first and skip",
+	"this step while a monitor for it is still running.",
+	"While a monitor is armed, keep `delaySeconds` at 1200-1800: the monitor is the wake signal and the",
+	"`schedule_wakeup` delay is only the fallback heartbeat. When a monitor event wakes you, handle the event,",
+	"then decide whether the loop continues.",
+].join("\n");
+
+/**
+ * Fill `{name}` placeholders. A replacer function is used so that `$&` or
+ * `$1` in a prompt are inserted literally.
+ */
+export function fill(template: string, values: Record<string, string>): string {
+	return template.replace(/\{(\w+)\}/g, (match, key: string) => values[key] ?? match);
+}
+
+/** The prompt as a JSON string: unambiguous even with quotes or newlines. */
+export function quote(prompt: string): string {
+	return JSON.stringify(prompt);
+}
+
+/** How a prompt is described to the model; the loop.md sentinel gets an explanation. */
+function describePrompt(prompt: string): string {
+	if (prompt !== LOOP_FILE_SENTINEL) return prompt;
+	return (
+		"the loop tasks in the message above (pass the literal sentinel " +
+		`${quote(LOOP_FILE_SENTINEL)} as \`prompt\`: it expands to the current loop.md tasks, or the built-in ` +
+		"maintenance pass when there is no loop.md, every time it fires)"
+	);
+}
+
+export function provenance(tick: number): string {
+	return fill(PROVENANCE, { n: String(tick) });
+}
+
+/** The header of a fixed-interval fire: a scheduled task, not a loop tick. */
+export function scheduledTaskProvenance(id: string, schedule: string): string {
+	return fill(SCHEDULED_TASK_PROVENANCE, { id, schedule });
+}
+
+export function loopCommandGuidelines(raw: string): string {
+	const quoted = quote(raw || LOOP_FILE_SENTINEL);
+	return fill(LOOP_COMMAND_GUIDELINES, {
+		raw: raw ? `${quote(raw)}` : "(empty: the loop.md tasks)",
+		quoted,
+		delayAdvice: DELAY_ADVICE,
+	}).replace(LOOP_FILE_SENTINEL_PLACEHOLDER, quote(LOOP_FILE_SENTINEL));
+}
+
+export function loopGuidelines(prompt: string): string {
+	return fill(LOOP_GUIDELINES, { prompt: describePrompt(prompt), quoted: quote(prompt) });
+}
+
+export function cronTickGuidelines(id: string, schedule: string): string {
+	return fill(CRON_TICK_GUIDELINES, { id, schedule });
+}
+
+export function monitorGuidelines(prompt: string): string {
+	return fill(MONITOR_GUIDELINES, { quoted: quote(prompt) });
+}
+
+/** Claude Code's notice for durable one-shot jobs that came due while nobody was running them. */
+export function missedJobsMessage(lines: string[]): string {
+	const one = lines.length === 1;
+	return [
+		"[missed scheduled jobs \u00b7 reported by /loop, not typed by the user]",
+		`The following one-shot scheduled task${one ? " was" : "s were"} missed while Pi was not running. ` +
+			`${one ? "It has" : "They have"} already been removed from .pi/scheduled_tasks.json.`,
+		`Do NOT execute ${one ? "this prompt" : "these prompts"} yet. First ask the user whether to run ` +
+			`${one ? "it" : "each one"} now. Only execute if the user confirms.`,
+		...lines,
+	].join("\n");
+}
+
+// ---------------------------------------------------------------- tools
+
+export const CRON_CREATE_DESCRIPTION = `Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.
+Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local \u2014 no timezone conversion needed.
+
+## One-shot tasks (recurring: false)
+For "remind me at X" or "at <time>, do Y" requests \u2014 fire once then auto-delete.
+Pin minute/hour/day-of-month/month to specific values:
+  "remind me at 2:30pm today to check the deploy" \u2192 cron: "30 14 <today_dom> <today_month> *", recurring: false
+  "tomorrow morning, run the smoke test" \u2192 cron: "57 8 <tomorrow_dom> <tomorrow_month> *", recurring: false
+
+## Recurring jobs (recurring: true, the default)
+For "every N minutes" / "every hour" / "weekdays at 9am" requests:
+  "*/5 * * * *" (every 5 min), "0 * * * *" (hourly), "0 9 * * 1-5" (weekdays at 9am local)
+
+## Avoid the :00 and :30 minute marks when the task allows it
+When the user's request is approximate, pick a minute that is NOT 0 or 30:
+  "every morning around 9" \u2192 "57 8 * * *" or "3 9 * * *" (not "0 9 * * *")
+  "hourly" \u2192 "7 * * * *" (not "0 * * * *")
+  "in an hour or so, remind me to..." \u2192 pick whatever minute you land on, don't round
+Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past").
+
+## Durability
+By default (durable: false) the job belongs to this Pi session: it is restored if the session is resumed and gone otherwise. Pass durable: true to write it to .pi/scheduled_tasks.json so it survives restarts; one Pi session per project runs the durable jobs. Only use durable: true when the user explicitly asks for the task to persist ("keep doing this every day", "set this up permanently").
+
+## Not for live watching
+cron_create re-runs a prompt at fixed wall-clock intervals. To watch a log file, process, or command output and be told the moment something changes, use the Monitor tool instead when it is available \u2014 it streams events as they happen; cron polls on a schedule.
+
+## Runtime behavior
+Jobs only fire while the agent is idle (not mid-turn). The scheduler shifts each job by a fixed per-job offset on top of whatever you pick: a recurring job runs up to half its period late (max 30 min), a "*/5 * * * *" job keeps its 5 minute cadence, late by that offset rather than early, and a one-shot job landing on :00 or :30 runs up to 90 s early. The result of this tool and of cron_list gives each job's actual next run time: when you tell the user when a job will run, give that time, not the minute in the cron expression.
+Recurring jobs auto-expire after 7 days \u2014 they fire one final time, then are deleted. Tell the user about the 7-day limit when scheduling recurring jobs.
+Returns a job ID you can pass to cron_delete.`;
+
+export const CRON_DELETE_DESCRIPTION =
+	"Cancel a job scheduled with cron_create, or end a self-paced /loop, by its id. Removes it from .pi/scheduled_tasks.json (durable jobs) or from this session (session-only jobs).";
+
+export const CRON_LIST_DESCRIPTION =
+	"List the scheduled jobs, both durable (.pi/scheduled_tasks.json) and session-only, with their ids, schedules, actual next run times and prompts.";
+
+export const SCHEDULE_WAKEUP_DESCRIPTION = `Schedule when to resume work in a self-paced /loop \u2014 the user invoked /loop without an interval, asking you to self-pace iterations of a task. Call it as the last thing in the turn to keep the loop alive: the turn ends as soon as it returns, so write your update for the user first. To end the loop, call it with stop: true (omit every other field).
+
+Pass the same /loop prompt back via \`prompt\` each turn so the next firing repeats the task. For a bare /loop (no prompt), pass the literal sentinel "${LOOP_FILE_SENTINEL}": it expands at fire time to the current loop.md tasks, or to the built-in maintenance pass when there is no loop.md.
+
+Do not schedule a short wakeup to poll for work Pi will tell you about anyway (a monitor event, a command you are running): schedule a long fallback (1200s+) so the loop survives if that never arrives. For external work nothing notifies you about (a CI run, a deploy, a remote queue), pick a delay matched to how fast that state actually changes.
+
+## Picking delaySeconds
+Pick the delay from what you are waiting for. When actively polling state nothing notifies you about, match how fast it changes and commit to it instead of stacking short waits. For idle ticks with no specific signal to watch, default to 1200-1800s (20-30 min). The runtime clamps to [60, 3600].
+
+## Only for self-paced loops
+A /loop started with an interval (for example /loop 5m ...) is a cron job: it fires its own ticks, and calling this from one of those ticks would run the prompt twice. Cancel that kind of loop with \`cron_delete\` instead.
+
+## The reason field
+One short sentence on what you chose and why. It is shown to the user: "watching CI run" beats "waiting".`;
+
+export const CRON_CREATE_SNIPPET = "Schedule a prompt on a 5-field cron expression, recurring or one-shot";
+export const CRON_DELETE_SNIPPET = "Cancel a scheduled job or a self-paced /loop by id";
+export const CRON_LIST_SNIPPET = "List scheduled jobs with their actual next run times";
+export const SCHEDULE_WAKEUP_SNIPPET = "Pick when a self-paced /loop runs next, or stop it";

package/render.ts

@@ -1,18 +1,21 @@
 /**
- * Rendering helpers for the pi-cc-loop custom messages.
+ * Rendering helpers for the pi-cc custom messages (loop ticks, monitor events).
  *
- * Pi renders a custom message with the raw `customType` as its title
- * (`[pi-cc-loop-tick]`), which reads like a machine name. A custom renderer
- * replaces that with either a quiet two-line block (the default) or the
- * legacy padded card, depending on `compactMessages`.
+ * Pi renders a custom message with its raw `customType` as the title, which
+ * reads like a machine name. A custom renderer replaces that with either a
+ * quiet block (the default) or the legacy padded card, depending on
+ * `compactMessages`.
  *
  * The quiet block is modelled on Claude Code's `scheduled_task_fire` marker:
- * a timestamped header plus the prompt. No icon and no background; the
- * accent-coloured label carries the meaning, and the timestamp makes a
- * minute-by-minute loop easy to scan.
+ * a timestamped header plus the text, with no icon and no background. Long
+ * text is capped to a few lines while collapsed; expanding shows all of it and
+ * the metadata.
  *
  * The renderer only affects the display. The message content the model sees is
  * unchanged.
+ *
+ * This file is identical in pi-cc-loop and pi-cc-monitor; tests/shared.test.mjs
+ * fails when the two copies drift apart.
  */
 
 import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
@@ -38,6 +41,22 @@ export function stripProvenance(text: string, pattern: RegExp): string {
 	return text.replace(pattern, "");
 }
 
+/** Cap a string for a display line, with an ellipsis. */
+export function truncate(text: string, max: number): string {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length <= max ? flat : `${flat.slice(0, Math.max(0, max - 1))}\u2026`;
+}
+
+/** "900ms", "5s", "1m 30s": a duration for a status line. */
+export function formatDuration(ms: number): string {
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const seconds = Math.round(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	const rest = seconds % 60;
+	return rest ? `${minutes}m ${rest}s` : `${minutes}m`;
+}
+
 /** The first non-empty line of a text block. */
 export function firstLine(text: string): string {
 	for (const line of text.split("\n")) {
@@ -63,7 +82,11 @@ export function formatStamp(epochMs: number | undefined): string {
 	const date = new Date(epochMs ?? Date.now());
 	if (Number.isNaN(date.getTime())) return "";
 	const now = new Date();
-	const time = date.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
+	// Claude Code's clock style: "6:16pm", lowercase, no space.
+	const hour = date.getHours();
+	const time = `${hour % 12 === 0 ? 12 : hour % 12}:${String(date.getMinutes()).padStart(2, "0")}${
+		hour < 12 ? "am" : "pm"
+	}`;
 	if (date.toDateString() === now.toDateString()) return time;
 	const day = date.toLocaleDateString(undefined, { month: "short", day: "numeric" });
 	return `${day} ${time}`;

package/renderers.ts

@@ -0,0 +1,98 @@
+/**
+ * The display helpers pi-cc-loop still needs: clock times, the coarse countdown
+ * for the footer, and the block a scheduled fire draws in the transcript. The
+ * /loop request itself is an ordinary user message, rendered by Pi.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { bodyLines, contentText, formatStamp, renderBlock, renderCard, stripProvenance } from "./render.ts";
+import { loadConfig } from "./config.ts";
+import { humanSchedule } from "./cron.ts";
+import { displayPrompt } from "./loopfile.ts";
+
+
+/**
+ * A clock time the way Claude Code writes it: "6:16pm". Formatted here rather
+ * than through the locale, so the transcript reads the same everywhere.
+ */
+export function formatClock(epochMs: number | undefined): string {
+	if (!epochMs) return "unknown";
+	const date = new Date(epochMs);
+	const hour = date.getHours();
+	const suffix = hour < 12 ? "am" : "pm";
+	const twelve = hour % 12 === 0 ? 12 : hour % 12;
+	return `${twelve}:${String(date.getMinutes()).padStart(2, "0")}${suffix}`;
+}
+
+/**
+ * A countdown for the footer: "3m", "<1m", "2h 15m". Rounded up and coarse on
+ * purpose, so the shared footer line is repainted at most once a minute.
+ */
+export function formatEta(ms: number): string {
+	const seconds = ms / 1000;
+	if (seconds < 60) return "<1m";
+	const minutes = Math.ceil(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const rest = minutes % 60;
+	return rest ? `${hours}h ${rest}m` : `${hours}h`;
+}
+
+/** What a tick carries for the renderer; the model reads `content`. */
+export interface ScheduledDetails {
+	kind?: "cron" | "wakeup";
+	tickCount?: number;
+	jobId?: string;
+	cron?: string;
+	prompt?: string;
+	reason?: string;
+	missed?: boolean;
+}
+
+/**
+ * Draw a scheduled fire the way Claude Code does: `✻ Running scheduled task ·
+ * 6:16pm`, then the task. The provenance line in `content` is addressed to the
+ * model ("started by the schedule...") and must not reach the reader.
+ */
+export function renderScheduledMessage(message: any, options: any, theme: Theme): any {
+	const details = (message.details ?? {}) as ScheduledDetails;
+	const prompt = details.prompt ?? stripProvenance(contentText(message.content), /^\[[^\]]*\]\n?/);
+	// A fixed interval fires a scheduled task; only a self-paced tick is a loop.
+	const label = details.missed
+		? "\u273b loop \u00b7 missed jobs"
+		: details.kind === "cron"
+			? "\u273b Running scheduled task"
+			: details.tickCount !== undefined
+				? `\u273b loop #${details.tickCount}`
+				: "\u273b loop";
+
+	if (!loadConfig().compactMessages) {
+		const header = details.missed ? label : `loop tick #${details.tickCount ?? "?"} \u00b7 ${displayPrompt(prompt)}`;
+		return renderCard({ header, body: prompt, expanded: options.expanded, outputPad: options.outputPad, theme });
+	}
+
+	const stamp = formatStamp(message.timestamp);
+	// The reason the model gave for this delay, in the header so the reader
+	// knows why the loop woke up without expanding anything.
+	const why = details.kind === "wakeup" && details.reason ? ` \u00b7 ${details.reason}` : "";
+	const header =
+		(stamp
+			? `${theme.fg("accent", theme.bold(label))}${theme.fg("dim", " \u00b7 ")}${theme.fg("muted", stamp)}`
+			: theme.fg("accent", theme.bold(label))) + (why ? theme.fg("dim", why) : "");
+
+	const meta: string[] = [];
+	if (details.jobId) meta.push(`job ${details.jobId}`);
+	if (details.kind === "cron" && details.cron) meta.push(humanSchedule(details.cron));
+	else if (!details.missed) meta.push("self-paced");
+	meta.push("scheduled by /loop");
+
+	return renderBlock({
+		header,
+		body: bodyLines(prompt),
+		meta,
+		expanded: options.expanded,
+		outputPad: options.outputPad,
+		theme,
+		maxBodyLines: 3,
+	});
+}