pi-wakeup 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# pi-wakeup
+
+A pi extension giving a running session two tools to pace itself — the pi analog of Claude Code's `ScheduleWakeup` in dynamic mode.
+
+## Tools
+
+- **`schedule_wakeup(delay_seconds, prompt, reason?)`** — ask to be woken after a delay. When the timer fires, `prompt` is delivered back into the session: immediately as a steered turn if the session is idle, or queued as a `followUp` if a turn is already running. `delay_seconds` is clamped to `[60, 3600]`. Returns a wakeup id.
+- **`cancel_wakeup(id?)`** — cancel one pending wakeup by id, or every pending wakeup when the id is omitted.
+
+Use it to re-check something without a human poking the session — a build that takes a few minutes, a remote queue, a rate-limit window — rather than busy-waiting.
+
+## Design
+
+- **Session-local.** A wakeup is an in-process `setTimeout`, not a cron job. It lives and dies with the session. This is deliberate: subagents and pacing in pi are in-process (the muster-teammate shape is shelved), and cross-session scheduling is a different product (`cron` + `pi -p`), not this tool.
+- **Busy-gated delivery.** `agent_start` / `agent_settled` track whether a turn is running; delivery picks `steer` (idle) or `followUp` (busy) accordingly, so a wakeup never interrupts a turn in flight.
+- **Best-effort.** Every handler and the timer callback swallow-and-log on error — a missed wakeup must never take the session process down. The pure decisions (clamp, delivery mode, message shape) live in `src/schedule.ts` and are unit-tested with zero mocking; `src/index.ts` is the thin pi wiring, in the same split the guardrails package uses.
+- **Persistence.** Each schedule / fire / cancel is written with `pi.appendEntry` so the session transcript records the wakeup lifecycle.
+
+## Known follow-up
+
+**Re-arming a pending wakeup across a session *resume* is not yet implemented.** The extension API exposes no entry read-back, and reconstructing pending wakeups by parsing the transcript blind is exactly the kind of vacuous code this project avoids. Within a live session, wakeups fire; a session closed with a pending wakeup drops it on resume. When pi exposes a custom-entry reader (or a resume hook carrying prior entries), `SessionStartEvent.reason === "resume"` is the place to re-arm from the persisted `wakeup_scheduled` / `wakeup_fired` / `wakeup_cancelled` records.
+
+## Tests
+
+`node --test src/*.test.ts` — pure clamp/delivery/message logic plus the wired tool behavior (registration, idle-vs-busy delivery, clamp, cancel-one, cancel-all, a throwing `sendMessage` contained, shutdown cleanup) against a fake pi with an injectable timer.
+
+## Install
+
+```sh
+pi install npm:pi-wakeup
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-wakeup",
+  "version": "0.1.0",
+  "description": "schedule_wakeup / cancel_wakeup for the pi coding agent: session-local self-pacing, the pi analog of Claude Code's ScheduleWakeup dynamic mode.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schuettc/pi-extensions.git",
+    "directory": "packages/pi-wakeup"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "wakeup",
+    "scheduling",
+    "self-pacing"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "typescript": "^5.6.0"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,179 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createWakeup } from "./index.ts";
+import type { Deps } from "./index.ts";
+
+type Timer = { fn: () => void; ms: number; cancelled: boolean };
+
+function harness(opts: { idle?: boolean; sendThrows?: boolean; idleThrows?: boolean } = {}) {
+  const idle = opts.idle ?? true;
+  const tools = new Map<string, any>();
+  const handlers = new Map<string, (event?: unknown, ctx?: unknown) => void>();
+  const sent: Array<{ msg: any; opts: any }> = [];
+  const entries: Array<{ type: string; data: any }> = [];
+  const notifies: Array<{ text: string; level: string }> = [];
+  const timers: Timer[] = [];
+
+  const ctx = {
+    isIdle: () => {
+      if (opts.idleThrows) throw new Error("stale ctx");
+      return idle;
+    },
+    ui: { notify: (text: string, level: string) => notifies.push({ text, level }) },
+  };
+
+  const pi = {
+    registerTool(t: any) {
+      tools.set(t.name, t);
+    },
+    on(ev: string, h: (event?: unknown, c?: unknown) => void) {
+      handlers.set(ev, h);
+    },
+    sendMessage(msg: any, o: any) {
+      if (opts.sendThrows) throw new Error("boom");
+      sent.push({ msg, opts: o });
+    },
+    appendEntry(type: string, data: any) {
+      entries.push({ type, data });
+    },
+  };
+
+  const deps: Deps = {
+    setTimer: (fn: () => void, ms: number) => {
+      const t: Timer = { fn, ms, cancelled: false };
+      timers.push(t);
+      return t;
+    },
+    clearTimer: (handle: unknown) => {
+      (handle as Timer).cancelled = true;
+    },
+    now: () => 1000,
+  };
+
+  createWakeup(pi, deps);
+  // Prime the captured ctx as a real session would via session_start.
+  handlers.get("session_start")?.(undefined, ctx);
+
+  const schedule = (params: any) =>
+    tools.get("schedule_wakeup").execute("call", params, undefined, undefined, ctx);
+  const cancel = (params: any) => tools.get("cancel_wakeup").execute("call", params);
+  const fire = (t: Timer) => {
+    if (!t.cancelled) t.fn();
+  };
+  return { tools, handlers, sent, entries, notifies, timers, schedule, cancel, fire };
+}
+
+test("registers both tools", () => {
+  const h = harness();
+  assert.ok(h.tools.has("schedule_wakeup"));
+  assert.ok(h.tools.has("cancel_wakeup"));
+});
+
+test("scheduling arms a timer, persists, and firing while idle steers a fresh turn", async () => {
+  const h = harness({ idle: true });
+  const res = await h.schedule({ delay_seconds: 120, prompt: "check the build", reason: "CI" });
+  assert.match(res.content[0].text, /waking in 120s/);
+  assert.equal(h.timers.length, 1);
+  assert.equal(h.timers[0].ms, 120000);
+  assert.ok(h.entries.some((e) => e.type === "wakeup_scheduled" && e.data.delaySeconds === 120));
+
+  h.fire(h.timers[0]);
+  assert.equal(h.sent.length, 1);
+  assert.equal(h.sent[0].opts.triggerTurn, true); // ALWAYS true — see the dispatch note
+  assert.equal(h.sent[0].opts.deliverAs, "steer");
+  assert.match(h.sent[0].msg.content, /check the build/);
+  assert.match(h.sent[0].msg.content, /CI/);
+  assert.equal(h.sent[0].msg.customType, "wakeup");
+  assert.ok(h.entries.some((e) => e.type === "wakeup_fired"));
+});
+
+test("firing while a turn is streaming keeps triggerTurn:true and queues as followUp", async () => {
+  const h = harness({ idle: false });
+  await h.schedule({ delay_seconds: 300, prompt: "ping" });
+  h.fire(h.timers[0]);
+  assert.equal(h.sent[0].opts.triggerTurn, true); // NOT false — false lands in pi's dead branch
+  assert.equal(h.sent[0].opts.deliverAs, "followUp");
+});
+
+test("delay is clamped up to the floor", async () => {
+  const h = harness();
+  const res = await h.schedule({ delay_seconds: 1, prompt: "x" });
+  assert.match(res.content[0].text, /waking in 60s/);
+  assert.equal(h.timers[0].ms, 60000);
+});
+
+test("delay is clamped down to the ceiling", async () => {
+  const h = harness();
+  const res = await h.schedule({ delay_seconds: 999999, prompt: "x" });
+  assert.match(res.content[0].text, /waking in 3600s/);
+  assert.equal(h.timers[0].ms, 3600000);
+});
+
+test("cancel_wakeup by id prevents delivery and records the cancel", async () => {
+  const h = harness();
+  const res = await h.schedule({ delay_seconds: 120, prompt: "x" });
+  const id = res.details.id;
+  const c = await h.cancel({ id });
+  assert.match(c.content[0].text, new RegExp(`Cancelled ${id}`));
+  assert.equal(h.timers[0].cancelled, true);
+  h.fire(h.timers[0]);
+  assert.equal(h.sent.length, 0);
+  assert.ok(h.entries.some((e) => e.type === "wakeup_cancelled" && e.data.id === id));
+});
+
+test("cancel_wakeup of an unknown id records NO cancel entry", async () => {
+  const h = harness();
+  const c = await h.cancel({ id: "wake-999" });
+  assert.match(c.content[0].text, /No pending wakeup wake-999/);
+  assert.equal(h.entries.filter((e) => e.type === "wakeup_cancelled").length, 0);
+});
+
+test("cancel_wakeup with no id cancels all pending", async () => {
+  const h = harness();
+  await h.schedule({ delay_seconds: 120, prompt: "a" });
+  await h.schedule({ delay_seconds: 200, prompt: "b" });
+  const res = await h.cancel({});
+  assert.match(res.content[0].text, /Cancelled 2 pending wakeups/);
+  h.timers.forEach(h.fire);
+  assert.equal(h.sent.length, 0);
+});
+
+test("cancel-all with nothing pending reports zero and records no entry", async () => {
+  const h = harness();
+  const res = await h.cancel({});
+  assert.match(res.content[0].text, /Cancelled 0 pending wakeups/);
+  assert.equal(h.entries.filter((e) => e.type === "wakeup_cancelled").length, 0);
+});
+
+test("a throwing sendMessage is contained, recorded as a failure, and the wakeup is not left armed", async () => {
+  const h = harness({ sendThrows: true });
+  await h.schedule({ delay_seconds: 120, prompt: "x" });
+  assert.doesNotThrow(() => h.fire(h.timers[0]));
+  // Observable: a delivery-failed entry (NOT a silent vanish), and no fired entry.
+  assert.equal(h.entries.filter((e) => e.type === "wakeup_delivery_failed").length, 1);
+  assert.equal(h.entries.filter((e) => e.type === "wakeup_fired").length, 0);
+  assert.equal(h.notifies.length, 1);
+  // Removed on the first fire: firing the same handle again does nothing new.
+  h.fire(h.timers[0]);
+  assert.equal(h.entries.filter((e) => e.type === "wakeup_delivery_failed").length, 1);
+});
+
+test("a stale ctx whose isIdle() throws (after /reload) does not crash the timer callback; delivers as followUp", async () => {
+  const h = harness({ idleThrows: true });
+  await h.schedule({ delay_seconds: 120, prompt: "x" });
+  assert.doesNotThrow(() => h.fire(h.timers[0]));
+  assert.equal(h.sent.length, 1);
+  assert.equal(h.sent[0].opts.triggerTurn, true);
+  assert.equal(h.sent[0].opts.deliverAs, "followUp"); // safe fallback: never "steer"
+});
+
+test("session_shutdown clears every timer and no wakeup can still deliver", async () => {
+  const h = harness();
+  await h.schedule({ delay_seconds: 120, prompt: "a" });
+  await h.schedule({ delay_seconds: 200, prompt: "b" });
+  h.handlers.get("session_shutdown")!();
+  assert.ok(h.timers.every((t) => t.cancelled));
+  // Even if a stray timer callback still ran, pending was cleared, so nothing delivers.
+  h.timers.forEach((t) => t.fn());
+  assert.equal(h.sent.length, 0);
+});

package/src/index.ts

@@ -0,0 +1,240 @@
+// pi-wakeup — schedule_wakeup / cancel_wakeup tools.
+//
+// The pi analog of Claude Code's ScheduleWakeup in dynamic mode: a running
+// session can pace itself, asking to be woken after a delay to re-check
+// something (a build, a remote queue) without a human poking it. Wakeups are
+// session-local — an in-process timer, not a cron job. The pure decisions
+// (clamp, delivery mode, message) live in schedule.ts; this file is the thin,
+// best-effort pi wiring, in the same split guardrails uses.
+//
+// Delivery: at fire time we ask pi's authoritative ctx.isIdle() rather than
+// tracking a local busy flag (which races the real streaming state), and we
+// always pass triggerTurn:true — pi's dispatch routes a triggerTurn:false
+// message into a dead branch that neither steers nor queues, so deliverAs is
+// only honoured alongside triggerTurn:true. Idle -> steer a fresh turn; busy
+// -> followUp after the current turn (never interrupts it).
+//
+// Persistence: each schedule / fire / cancel / delivery-failure is written with
+// pi.appendEntry so the session transcript records the wakeup lifecycle.
+// Re-arming a pending wakeup across a session RESUME is a documented follow-up
+// (the extension API exposes no entry read-back). Within a live session,
+// wakeups fire.
+
+import {
+  clampDelaySeconds,
+  deliveryMode,
+  wakeupMessage,
+} from "./schedule.ts";
+
+type Pending = { prompt: string; reason: string };
+
+export type Deps = {
+  // Injectable so the wiring is testable without real time passing. Default to
+  // the globals; a test passes controllable stand-ins.
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+  now?: () => number;
+};
+
+const SCHEDULE_PARAMS = {
+  type: "object",
+  properties: {
+    delay_seconds: {
+      type: "number",
+      description: "Seconds from now to wake up. Clamped to [60, 3600].",
+    },
+    prompt: {
+      type: "string",
+      description: "The message delivered back into the session when the wakeup fires.",
+    },
+    reason: {
+      type: "string",
+      description: "One short line on why you are waking up. Shown with the delivered prompt.",
+    },
+  },
+  required: ["delay_seconds", "prompt"],
+};
+
+const CANCEL_PARAMS = {
+  type: "object",
+  properties: {
+    id: {
+      type: "string",
+      description: "The wakeup id to cancel. Omit to cancel every pending wakeup.",
+    },
+  },
+};
+
+export function createWakeup(pi: any, deps: Deps = {}): void {
+  const setTimer =
+    deps.setTimer ??
+    ((fn: () => void, ms: number) => {
+      const handle = setTimeout(fn, ms);
+      // Don't let a pending wakeup hold the event loop open on an exit path
+      // that skips session_shutdown. Interactive sessions keep other handles
+      // alive, so the timer still fires.
+      const unrefable = handle as { unref?: () => void };
+      if (typeof unrefable.unref === "function") unrefable.unref();
+      return handle;
+    });
+  const clearTimer =
+    deps.clearTimer ?? ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+  const now = deps.now ?? (() => Date.now());
+
+  const pending = new Map<string, Pending>();
+  const timers = new Map<string, unknown>();
+  // The session context, captured from session_start and refreshed on each
+  // tool call; deliver() reads ctx.isIdle() at fire time.
+  let ctx: any;
+  let counter = 0;
+
+  function log(message: string): void {
+    try {
+      process.stderr.write(`[wakeup] ${message}\n`);
+    } catch {
+      // best-effort logging
+    }
+  }
+
+  function forget(id: string): void {
+    const handle = timers.get(id);
+    if (handle !== undefined) clearTimer(handle);
+    timers.delete(id);
+    pending.delete(id);
+  }
+
+  function deliver(id: string): void {
+    const w = pending.get(id);
+    if (!w) return;
+    // Remove BEFORE delivering: one-shot, and a throw in sendMessage must not
+    // leave a half-fired wakeup armed.
+    forget(id);
+    // Reading ctx.isIdle() can THROW: a ctx captured at session_start goes
+    // stale after /reload, fork, or a session switch (assertActive() throws),
+    // and this runs up to an hour later inside a setTimeout callback where an
+    // escaped throw would kill the pi process. Guard it, and default idle=false
+    // on any failure — with triggerTurn:true, "followUp" is safe whether or not
+    // a turn is streaming (it queues when busy and still starts a turn when
+    // idle), whereas "steer" would interrupt a live turn.
+    let idle = false;
+    try {
+      idle = ctx && typeof ctx.isIdle === "function" ? Boolean(ctx.isIdle()) : false;
+    } catch {
+      idle = false;
+    }
+    try {
+      pi.sendMessage(
+        { content: wakeupMessage(w.prompt, w.reason), customType: "wakeup", display: true },
+        { triggerTurn: true, deliverAs: deliveryMode(idle) },
+      );
+    } catch (error) {
+      // A throw here runs inside the timer callback; uncaught it would kill the
+      // pi process. Contain it, and make the loss OBSERVABLE — a silently
+      // vanished wakeup is the worst outcome for a self-pacing tool.
+      log(`delivery of ${id} failed: ${String(error)}`);
+      try {
+        pi.appendEntry?.("wakeup_delivery_failed", { id, error: String(error) });
+      } catch {
+        // best-effort persistence
+      }
+      try {
+        ctx?.ui?.notify?.(`wakeup ${id} could not be delivered: ${String(error)}`, "error");
+      } catch {
+        // best-effort surface
+      }
+      return;
+    }
+    try {
+      pi.appendEntry?.("wakeup_fired", { id, reason: w.reason });
+    } catch {
+      // best-effort persistence
+    }
+  }
+
+  pi.on("session_start", (_event: unknown, sessionCtx: any) => {
+    ctx = sessionCtx;
+  });
+  pi.on("session_shutdown", () => {
+    for (const handle of timers.values()) clearTimer(handle);
+    timers.clear();
+    pending.clear();
+  });
+
+  pi.registerTool({
+    name: "schedule_wakeup",
+    label: "Schedule Wakeup",
+    description:
+      "Ask to be woken after a delay to re-check something without a human prompting you. The prompt is delivered back into this session when the timer fires (steered immediately if idle, queued after the current turn if busy). Session-local; delay clamped to [60, 3600] seconds.",
+    promptSnippet: "schedule_wakeup(delay_seconds, prompt, reason?) — self-pace: wake this session after a delay",
+    parameters: SCHEDULE_PARAMS,
+    async execute(
+      _id: string,
+      params: { delay_seconds: number; prompt: string; reason?: string },
+      _signal: unknown,
+      _onUpdate: unknown,
+      execCtx: any,
+    ) {
+      if (execCtx) ctx = execCtx;
+      const delay = clampDelaySeconds(params.delay_seconds);
+      const prompt = typeof params.prompt === "string" ? params.prompt : "";
+      const reason = typeof params.reason === "string" ? params.reason : "";
+      counter += 1;
+      const id = `wake-${counter}`;
+      const fireAtMs = now() + delay * 1000;
+      pending.set(id, { prompt, reason });
+      const handle = setTimer(() => deliver(id), delay * 1000);
+      timers.set(id, handle);
+      try {
+        pi.appendEntry?.("wakeup_scheduled", { id, delaySeconds: delay, reason, fireAtMs });
+      } catch {
+        // best-effort persistence
+      }
+      const reasonText = reason ? ` (${reason})` : "";
+      return {
+        content: [{ type: "text", text: `Scheduled ${id}: waking in ${delay}s${reasonText}.` }],
+        details: { id, delaySeconds: delay },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "cancel_wakeup",
+    label: "Cancel Wakeup",
+    description:
+      "Cancel a pending wakeup by id, or omit the id to cancel every pending wakeup in this session.",
+    promptSnippet: "cancel_wakeup(id?) — cancel a pending wakeup, or all of them",
+    parameters: CANCEL_PARAMS,
+    async execute(_id: string, params: { id?: string }) {
+      if (params && typeof params.id === "string" && params.id) {
+        const existed = pending.has(params.id);
+        forget(params.id);
+        if (existed) {
+          try {
+            pi.appendEntry?.("wakeup_cancelled", { id: params.id });
+          } catch {
+            // best-effort persistence
+          }
+        }
+        return {
+          content: [
+            { type: "text", text: existed ? `Cancelled ${params.id}.` : `No pending wakeup ${params.id}.` },
+          ],
+        };
+      }
+      const count = pending.size;
+      for (const id of [...pending.keys()]) forget(id);
+      if (count > 0) {
+        try {
+          pi.appendEntry?.("wakeup_cancelled", { all: true, count });
+        } catch {
+          // best-effort persistence
+        }
+      }
+      return { content: [{ type: "text", text: `Cancelled ${count} pending wakeup${count === 1 ? "" : "s"}.` }] };
+    },
+  });
+}
+
+export default function (pi: any) {
+  createWakeup(pi);
+}

package/src/schedule.test.ts

@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  clampDelaySeconds,
+  deliveryMode,
+  wakeupMessage,
+  MIN_DELAY_SECONDS,
+  MAX_DELAY_SECONDS,
+} from "./schedule.ts";
+
+test("clampDelaySeconds: below the floor clamps up to the minimum", () => {
+  assert.equal(clampDelaySeconds(1), MIN_DELAY_SECONDS);
+  assert.equal(clampDelaySeconds(0), MIN_DELAY_SECONDS);
+  assert.equal(clampDelaySeconds(-100), MIN_DELAY_SECONDS);
+  assert.equal(clampDelaySeconds(59), MIN_DELAY_SECONDS);
+});
+
+test("clampDelaySeconds: above the ceiling clamps down to the maximum", () => {
+  assert.equal(clampDelaySeconds(3601), MAX_DELAY_SECONDS);
+  assert.equal(clampDelaySeconds(999999), MAX_DELAY_SECONDS);
+});
+
+test("clampDelaySeconds: an in-range value is floored, not rounded", () => {
+  assert.equal(clampDelaySeconds(120), 120);
+  assert.equal(clampDelaySeconds(120.9), 120);
+  assert.equal(clampDelaySeconds(MIN_DELAY_SECONDS), MIN_DELAY_SECONDS);
+  assert.equal(clampDelaySeconds(MAX_DELAY_SECONDS), MAX_DELAY_SECONDS);
+});
+
+test("clampDelaySeconds: a non-finite or non-numeric delay falls back to the minimum, never throws", () => {
+  assert.equal(clampDelaySeconds(Number.NaN), MIN_DELAY_SECONDS);
+  assert.equal(clampDelaySeconds(Number.POSITIVE_INFINITY), MIN_DELAY_SECONDS);
+  // @ts-expect-error — deliberately passing a bad type the schema might miss
+  assert.equal(clampDelaySeconds("120"), MIN_DELAY_SECONDS);
+  // @ts-expect-error
+  assert.equal(clampDelaySeconds(undefined), MIN_DELAY_SECONDS);
+});
+
+test("deliveryMode: idle steers a fresh turn, busy queues as followUp", () => {
+  assert.equal(deliveryMode(true), "steer"); // idle
+  assert.equal(deliveryMode(false), "followUp"); // busy/streaming
+});
+
+test("wakeupMessage: a reason is appended in parentheses", () => {
+  assert.equal(
+    wakeupMessage("check the build", "waiting on CI"),
+    "check the build\n\n(scheduled wakeup — waiting on CI)",
+  );
+});
+
+test("wakeupMessage: an empty or whitespace reason leaves the prompt bare", () => {
+  assert.equal(wakeupMessage("check the build", ""), "check the build");
+  assert.equal(wakeupMessage("check the build", "   "), "check the build");
+});

package/src/schedule.ts

@@ -0,0 +1,41 @@
+// Pure decision logic for the wakeup extension. No pi imports, no timers,
+// no I/O — so every rule here is exercised by node --test with zero mocking,
+// exactly the split the guardrails package uses (gate.ts vs index.ts).
+
+// pi-side clamp matching Claude Code's ScheduleWakeup: a wakeup delay under a
+// minute would busy-loop the session, and one over an hour is a scheduler's
+// job, not a session's self-pacing tool.
+export const MIN_DELAY_SECONDS = 60;
+export const MAX_DELAY_SECONDS = 3600;
+
+// Clamp an arbitrary caller-supplied delay into [MIN, MAX]. A non-finite or
+// non-numeric value (the model omitted it, or sent a string that slipped the
+// schema) falls back to the minimum rather than throwing — a guardrail tool
+// must never fail the turn over a bad argument.
+export function clampDelaySeconds(seconds: number): number {
+  if (typeof seconds !== "number" || !Number.isFinite(seconds)) return MIN_DELAY_SECONDS;
+  const floored = Math.floor(seconds);
+  if (floored < MIN_DELAY_SECONDS) return MIN_DELAY_SECONDS;
+  if (floored > MAX_DELAY_SECONDS) return MAX_DELAY_SECONDS;
+  return floored;
+}
+
+// How to deliver a fired wakeup, given the session's authoritative idle state
+// (ctx.isIdle()). When idle we steer a fresh turn; when a turn is already
+// streaming we queue as a followUp so the wakeup lands after it rather than
+// interrupting it. NOTE: the caller always passes triggerTurn:true — pi's
+// dispatch only honours deliverAs while streaming, and routes a
+// triggerTurn:false message into a dead branch that neither steers nor queues.
+export type DeliveryMode = "steer" | "followUp";
+export function deliveryMode(idle: boolean): DeliveryMode {
+  return idle ? "steer" : "followUp";
+}
+
+// The message content a fired wakeup delivers into the session. The reason is
+// appended in parentheses so the woken turn can see why it was scheduled,
+// mirroring the `reason` field ScheduleWakeup surfaces back to the user.
+export function wakeupMessage(prompt: string, reason: string): string {
+  const trimmedReason = typeof reason === "string" ? reason.trim() : "";
+  const suffix = trimmedReason ? `\n\n(scheduled wakeup — ${trimmedReason})` : "";
+  return `${prompt}${suffix}`;
+}