pi-mox 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Each release of `pi-mox`. Versions follow [semantic versioning](https://semver.org); before 1.0.0 a minor
+version may add commands and options and a patch version fixes.
+
+## Unreleased
+
+## 0.1.0
+
+### Added
+
+- `/mox <time> <message>` schedules a message for the agent. At that time the message is delivered as a
+  follow-up (after the current turn, or at once when Pi is idle) and starts a turn.
+- Absolute times `10:30` (24-hour; today, or tomorrow when the time is not ahead) and relative times
+  `+2h15m`, `+90m`, `+45s`.
+- `/mox list` (or bare `/mox`) shows the pending cues; `/mox cancel <id>` cancels one by Roman or Arabic id.
+  Several cues can wait at once, and ids are never reused within a session.
+- Footer `·MOX· 10:30 · II h VI m` for the next cue, with `(+N)` when more wait.
+- The delivered message is shown as `·MOX· 10:30 — <message>`.
+- Cues live in memory only: closing Pi drops them. Each fires once and is not retried.

package/LICENSE

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

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# pi-mox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Schedule a message for the agent in [Pi](https://github.com/earendil-works/pi). Say when, say what, and at
+that time the message reaches the agent and starts a turn. *Mox* is Latin for "soon".
+
+Typical use: the session's quota runs out and says it refreshes at 10:30, but it is 8:24. Schedule the
+next step once and walk away:
+
+```
+/mox 10:30 continúa con T3
+```
+
+## Install
+
+```
+pi install npm:pi-mox
+```
+
+## Usage
+
+| Command | What it does |
+| --- | --- |
+| `/mox <time> <message>` | Deliver `<message>` to the agent at `<time>` |
+| `/mox list` (or `/mox`) | Show the pending cues |
+| `/mox cancel <id>` | Cancel a cue; the id is Roman (`II`, `ii`) or Arabic (`2`) |
+
+`list` and `cancel` are reserved first words.
+
+### Time
+
+- Absolute: `10:30` or `9:05`, 24-hour (`0:00`–`23:59`). Today at that time; if it is equal to or before now,
+  tomorrow. `24:00`, `10:60` and `1030` are rejected.
+- Relative: `+` followed by `<n>h`, `<n>m`, `<n>s` in that order: `+2h15m`, `+90m`, `+45s`, `+1h30s`.
+  The total must be above zero.
+
+The message is the rest of the line, trimmed and delivered verbatim.
+
+### Examples
+
+```
+/mox 10:30 continúa con T3
+Scheduled I for 10:30 (in 2h06m): continúa con T3
+
+/mox +5h36m corre la suite
+Scheduled II for 14:00 (in 5h36m): corre la suite
+
+/mox list
+I   10:30  2h06m  continúa con T3
+II  14:00  5h36m  corre la suite
+
+/mox cancel II
+Cancelled II (14:00): corre la suite
+```
+
+The footer shows the next cue, with the time left in Roman numerals (hours omitted at zero, minutes rounded
+up, under a minute shows `I m`), and `(+N)` when more cues wait:
+
+```
+·MOX· 10:30 · II h VI m (+1)
+```
+
+When a cue is due, the agent receives the message and the conversation shows:
+
+```
+·MOX· 10:30 — continúa con T3
+```
+
+Errors (bad time, missing message, unknown id) are shown with a usage line and change nothing.
+
+## Behavior
+
+- **Delivery.** The message is sent as a follow-up that triggers a turn: when Pi is idle a turn starts at
+  once; when Pi is busy the message waits for the current run to finish.
+- **One shot.** A cue fires once and is removed. If delivery fails the error is shown like any other error;
+  there is no retry.
+- **In memory.** Cues are kept only while Pi runs. Closing Pi (or ending the session) drops them.
+- **Wall clock.** The next cue is checked against the clock at least every 30 seconds, so a cue that came due
+  while the computer was suspended is delivered as soon as it resumes. Timers never keep Pi from exiting.
+- **Ids.** Roman numerals counting up from `I` in each session; an id is never reused, even after a cue is
+  cancelled or fired.
+
+## Development
+
+Requires Node.js 22.18 or newer (the sources are TypeScript run with type stripping; there is no build).
+
+```
+npm test
+```
+
+- `src/mox.ts`: core with no Pi runtime imports: time parsing, Roman numerals, the cue list and scheduler
+  (injectable clock and timers), the command runner.
+- `src/wire.ts`: connects the core to Pi's extension API.
+- `extensions/mox.ts`: the package's Pi extension entry.
+
+## Releasing
+
+Branches: work goes to `develop` through pull requests; `main` receives `develop` when a release closes.
+
+1. On a `release/X.Y.Z` branch from `develop`: set `version` in `package.json`, rename `## Unreleased` in `CHANGELOG.md` to `## X.Y.Z`, and commit `release X.Y.Z: <summary>`. Merge it into `develop`, then `develop` into `main`.
+2. Tag `main` with `vX.Y.Z` and push the tag.
+3. The [release workflow](.github/workflows/release.yml) checks the tag against `package.json` and `CHANGELOG.md`, runs the tests, and stages the version on npm through trusted publishing, with provenance. Approve it with 2FA: `npm stage list`, then `npm stage approve <id>`, or on npmjs.com. It then creates the GitHub release with the version's CHANGELOG section as notes.
+
+## License
+
+MIT

package/extensions/mox.ts

@@ -0,0 +1,8 @@
+// pi-mox: schedule a message for the agent. Adds /mox, the ·MOX· footer and the delivered-message renderer.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { registerMox } from "../src/wire.ts";
+
+export default function (pi: ExtensionAPI) {
+	registerMox(pi, { Text });
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "pi-mox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Schedule a message for the agent in Pi: /mox 10:30 <message> delivers it at that time and starts a turn.",
+  "license": "MIT",
+  "author": "jals1212",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jals1212/pi-mox.git"
+  },
+  "homepage": "https://github.com/jals1212/pi-mox#readme",
+  "bugs": "https://github.com/jals1212/pi-mox/issues",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "mox",
+    "schedule",
+    "reminder",
+    "agent"
+  ],
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./extensions/mox.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "test": "node --test \"tests/*.test.ts\""
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/mox.ts

@@ -0,0 +1,313 @@
+// pi-mox core: time parsing, Roman numerals, the cue list and its wall-clock scheduler, and the /mox command.
+// No Pi runtime imports here (see src/wire.ts for the wiring), so everything runs under plain `node --test`.
+
+export const USAGE = "Usage: /mox <time> <message>, /mox list, /mox cancel <id> (time: 10:30 or +2h15m)";
+
+/** A pending cue: a message to deliver at `at` (epoch milliseconds). `id` is shown as a Roman numeral. */
+export interface Cue {
+	id: number;
+	at: number;
+	message: string;
+}
+
+export interface Timers {
+	setTimer(fn: () => void, ms: number): unknown;
+	clearTimer(handle: unknown): void;
+}
+
+export interface MoxOptions extends Timers {
+	now(): number;
+	/** Deliver a due cue. Called once per cue, in time order; a throw goes to `onError`, never retried. */
+	send(cue: Cue): void;
+	/** Show the footer text, or clear it (`undefined`). */
+	setStatus(text: string | undefined): void;
+	onError?(error: unknown, cue: Cue): void;
+	/** Paint the footer with ANSI colors (only when there is a UI). */
+	color?(): boolean;
+}
+
+export interface Mox {
+	add(at: number, message: string): Cue;
+	cancel(id: number): Cue | undefined;
+	/** Pending cues, nearest first. */
+	list(): Cue[];
+	/** Clear every timer, cue and the footer; ids start again from I. */
+	shutdown(): void;
+}
+
+export interface CommandDeps {
+	ctx: { hasUI: boolean; ui: { notify(message: string, type?: "info" | "warning" | "error"): void } };
+	mox: Mox;
+	now(): number;
+}
+
+// --- Colors (24-bit ANSI): bronze and marble gray. ---
+
+const BRONZE = [205, 127, 50] as const; // #CD7F32
+const MARBLE = [184, 184, 176] as const; // #B8B8B0
+
+const paint = (rgb: readonly [number, number, number], text: string, on: boolean): string =>
+	on ? `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\x1b[39m` : text;
+
+const BRAND = "·MOX·";
+
+// --- Roman numerals ---
+
+const ROMAN: [number, string][] = [[1000, "M"], [900, "CM"], [500, "D"], [400, "CD"], [100, "C"], [90, "XC"], [50, "L"], [40, "XL"], [10, "X"], [9, "IX"], [5, "V"], [4, "IV"], [1, "I"]];
+
+/** Canonical Roman numeral for 1..3999; larger numbers (and anything below 1) fall back to Arabic digits. */
+export function toRoman(n: number): string {
+	if (!Number.isInteger(n) || n < 1 || n > 3999) return String(n);
+	let rest = n;
+	let out = "";
+	for (const [value, letters] of ROMAN) {
+		while (rest >= value) {
+			out += letters;
+			rest -= value;
+		}
+	}
+	return out;
+}
+
+/** The number a canonical Roman numeral (any case) stands for, or undefined. */
+export function fromRoman(text: string): number | undefined {
+	const upper = text.toUpperCase();
+	if (!/^[IVXLCDM]+$/.test(upper)) return undefined;
+	let total = 0;
+	let rest = upper;
+	for (const [value, letters] of ROMAN) {
+		while (rest.startsWith(letters)) {
+			total += value;
+			rest = rest.slice(letters.length);
+		}
+	}
+	return rest === "" && total <= 3999 && toRoman(total) === upper ? total : undefined;
+}
+
+// --- Time ---
+
+const pad2 = (n: number) => String(n).padStart(2, "0");
+
+/** Local HH:MM. */
+export function formatClock(at: number): string {
+	const d = new Date(at);
+	return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+const minutesLeft = (ms: number) => Math.max(1, Math.ceil(ms / 60_000));
+
+/** Remaining time for lists: `2h06m`, or `45m` under an hour; minutes rounded up. */
+export function formatRemaining(ms: number): string {
+	const total = minutesLeft(ms);
+	const hours = Math.floor(total / 60);
+	return hours > 0 ? `${hours}h${pad2(total % 60)}m` : `${total}m`;
+}
+
+/** Remaining time for the footer, in Roman numerals: `II h VI m`; hours omitted at 0, minutes at 0. */
+export function formatRemainingRoman(ms: number): string {
+	const total = minutesLeft(ms);
+	const hours = Math.floor(total / 60);
+	const minutes = total % 60;
+	const parts: string[] = [];
+	if (hours > 0) parts.push(`${toRoman(hours)} h`);
+	if (minutes > 0) parts.push(`${toRoman(minutes)} m`);
+	return parts.join(" ");
+}
+
+const ABSOLUTE = /^(\d{1,2}):(\d{2})$/;
+const RELATIVE = /^\+(?:(\d{1,7})h)?(?:(\d{1,7})m)?(?:(\d{1,7})s)?$/;
+
+/**
+ * Epoch milliseconds for a time token, or undefined when it is not valid.
+ * `H:MM`/`HH:MM` (24-hour) is today, or tomorrow when that time is not after `now`;
+ * `+2h15m`, `+90m`, `+45s` (h, m, s in that order, total > 0) is that long from `now`.
+ */
+export function parseSchedule(token: string, now: number): number | undefined {
+	const abs = ABSOLUTE.exec(token);
+	if (abs) {
+		const hours = Number(abs[1]);
+		const minutes = Number(abs[2]);
+		if (hours > 23 || minutes > 59) return undefined;
+		const target = new Date(now);
+		target.setHours(hours, minutes, 0, 0);
+		if (target.getTime() <= now) target.setDate(target.getDate() + 1);
+		return target.getTime();
+	}
+	const rel = RELATIVE.exec(token);
+	if (rel && (rel[1] !== undefined || rel[2] !== undefined || rel[3] !== undefined)) {
+		const total = (Number(rel[1] ?? 0) * 3600 + Number(rel[2] ?? 0) * 60 + Number(rel[3] ?? 0)) * 1000;
+		return total > 0 ? now + total : undefined;
+	}
+	return undefined;
+}
+
+// --- Timers ---
+
+/** Real timers; the handle is unref'd so a pending cue never keeps Pi alive. */
+export const defaultTimers: Timers = {
+	setTimer(fn, ms) {
+		const handle = setTimeout(fn, ms);
+		handle.unref();
+		return handle;
+	},
+	clearTimer: (handle) => clearTimeout(handle as NodeJS.Timeout),
+};
+
+// --- Cue list and scheduler ---
+
+/** The timer re-checks the wall clock at least this often, so a machine that slept fires overdue cues on waking. */
+const TICK_MS = 30_000;
+
+const byTime = (a: Cue, b: Cue) => a.at - b.at || a.id - b.id;
+
+export function createMox(options: MoxOptions): Mox {
+	let cues: Cue[] = [];
+	let nextId = 1;
+	let handle: unknown;
+	let armed = false;
+
+	const statusText = (): string | undefined => {
+		const sorted = [...cues].sort(byTime);
+		const next = sorted[0];
+		if (!next) return undefined;
+		const more = sorted.length > 1 ? ` (+${sorted.length - 1})` : "";
+		const rest = `${formatClock(next.at)} · ${formatRemainingRoman(next.at - options.now())}${more}`;
+		const color = options.color?.() ?? false;
+		return `${paint(BRONZE, BRAND, color)} ${paint(MARBLE, rest, color)}`;
+	};
+
+	const disarm = () => {
+		if (armed) options.clearTimer(handle);
+		armed = false;
+	};
+
+	const arm = () => {
+		disarm();
+		const next = [...cues].sort(byTime)[0];
+		if (!next) return;
+		handle = options.setTimer(tick, Math.max(0, Math.min(TICK_MS, next.at - options.now())));
+		armed = true;
+	};
+
+	const tick = () => {
+		armed = false;
+		const now = options.now();
+		const due = cues.filter((cue) => cue.at <= now).sort(byTime);
+		cues = cues.filter((cue) => cue.at > now);
+		for (const cue of due) {
+			try {
+				options.send(cue);
+			} catch (error) {
+				options.onError?.(error, cue);
+			}
+		}
+		options.setStatus(statusText());
+		arm();
+	};
+
+	const changed = () => {
+		options.setStatus(statusText());
+		arm();
+	};
+
+	return {
+		add(at, message) {
+			const cue = { id: nextId++, at, message };
+			cues.push(cue);
+			changed();
+			return cue;
+		},
+		cancel(id) {
+			const cue = cues.find((candidate) => candidate.id === id);
+			if (!cue) return undefined;
+			cues = cues.filter((candidate) => candidate !== cue);
+			changed();
+			return cue;
+		},
+		list: () => [...cues].sort(byTime).map((cue) => ({ ...cue })),
+		shutdown() {
+			disarm();
+			cues = [];
+			nextId = 1;
+			options.setStatus(undefined);
+		},
+	};
+}
+
+// --- Command ---
+
+const dayStart = (ms: number) => new Date(new Date(ms).setHours(0, 0, 0, 0)).getTime();
+
+function dayLabel(at: number, now: number): string {
+	const days = Math.round((dayStart(at) - dayStart(now)) / 86_400_000);
+	if (days === 0) return "";
+	if (days === 1) return " tomorrow";
+	const d = new Date(at);
+	return ` ${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+/** `/mox <args>`: schedule, list or cancel. Results and errors go through `ctx.ui.notify`. */
+export function runMoxCommand(args: string, deps: CommandDeps): void {
+	const { ctx, mox } = deps;
+	const info = (message: string) => ctx.ui.notify(message, "info");
+	const fail = (message: string) => ctx.ui.notify(`${message}\n${USAGE}`, "error");
+	const text = args.trim();
+	const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(text);
+	const word = match?.[1];
+	const rest = match?.[2]?.trim() ?? "";
+
+	if (word === undefined || word === "list") {
+		if (rest !== "") return fail("list takes no arguments.");
+		const cues = mox.list();
+		if (cues.length === 0) return info("No pending cues.");
+		const now = deps.now();
+		const width = Math.max(2, ...cues.map((cue) => toRoman(cue.id).length));
+		return info(
+			cues
+				.map((cue) => {
+					const line = `${formatClock(cue.at)}  ${formatRemaining(cue.at - now)}  ${cue.message}`;
+					return `${paint(BRONZE, toRoman(cue.id).padEnd(width), ctx.hasUI)}  ${paint(MARBLE, line, ctx.hasUI)}`;
+				})
+				.join("\n"),
+		);
+	}
+
+	if (word === "cancel") {
+		if (rest === "") return fail("Missing cue id.");
+		const id = /^\d+$/.test(rest) ? Number(rest) : fromRoman(rest);
+		if (id === undefined || id < 1) return fail(`Invalid cue id "${rest}".`);
+		const cue = mox.cancel(id);
+		if (!cue) return fail(`No pending cue ${toRoman(id)}.`);
+		return info(`Cancelled ${toRoman(cue.id)} (${formatClock(cue.at)}): ${cue.message}`);
+	}
+
+	const now = deps.now();
+	const at = parseSchedule(word, now);
+	if (at === undefined) return fail(`Invalid time "${word}".`);
+	if (rest === "") return fail("Missing message.");
+	const cue = mox.add(at, rest);
+	info(`Scheduled ${toRoman(cue.id)} for ${formatClock(at)}${dayLabel(at, now)} (in ${formatRemaining(at - now)}): ${rest}`);
+}
+
+/** Autocompletion: `list`, `cancel`, and pending ids after `cancel`. */
+export function completeMoxArgs(prefix: string, mox: Mox): { value: string; label: string }[] | null {
+	const words = prefix.split(" ");
+	if (words.length === 1) {
+		const items = ["list", "cancel"].filter((sub) => sub.startsWith(words[0])).map((sub) => ({ value: sub, label: sub }));
+		return items.length > 0 ? items : null;
+	}
+	if (words.length !== 2 || words[0] !== "cancel") return null;
+	const typed = words[1].toUpperCase();
+	const items = mox
+		.list()
+		.sort((a, b) => a.id - b.id)
+		.filter((cue) => toRoman(cue.id).startsWith(typed) || String(cue.id).startsWith(typed))
+		.map((cue) => ({ value: `cancel ${toRoman(cue.id)}`, label: `${toRoman(cue.id)}  ${formatClock(cue.at)}  ${cue.message}` }));
+	return items.length > 0 ? items : null;
+}
+
+/** Text of a delivered cue: `·MOX· 10:30 — <message>`, ·MOX· in bronze, the rest in marble. */
+export function renderMoxText(content: string, at: number | undefined): string {
+	const body = at === undefined ? content : `${formatClock(at)} — ${content}`;
+	return `${paint(BRONZE, BRAND, true)} ${paint(MARBLE, body, true)}`;
+}

package/src/wire.ts

@@ -0,0 +1,70 @@
+// pi-mox wiring: connects the core (src/mox.ts) to Pi's extension API. Pi runtime values (the `Text` component)
+// are passed in by extensions/mox.ts, so this file has type-only imports and runs under plain `node --test`.
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Text } from "@earendil-works/pi-tui";
+import { completeMoxArgs, createMox, defaultTimers, renderMoxText, runMoxCommand, toRoman, type Timers } from "./mox.ts";
+
+export interface WireOptions {
+	Text: typeof Text;
+	now?: () => number;
+	timers?: Timers;
+	/** Where notifications go when there is no UI (print and JSON modes); stdout stays free for Pi's output. */
+	stderr?: (text: string) => void;
+}
+
+export function registerMox(pi: ExtensionAPI, options: WireOptions): void {
+	const now = options.now ?? Date.now;
+	const timers = options.timers ?? defaultTimers;
+	const stderr = options.stderr ?? ((text: string) => void process.stderr.write(text));
+
+	// The UI of the latest session or command context; cues are shared by the whole Pi process.
+	let ui: { hasUI: boolean; ui: ExtensionContext["ui"] } | undefined;
+	const use = (ctx: ExtensionContext) => {
+		ui = { hasUI: ctx.hasUI, ui: ctx.ui };
+	};
+	const notify = (message: string, type: "info" | "warning" | "error" = "info") => {
+		if (ui?.hasUI) ui.ui.notify(message, type);
+		else stderr(`${message}\n`);
+	};
+
+	const mox = createMox({
+		...timers,
+		now,
+		color: () => ui?.hasUI === true,
+		setStatus: (text) => {
+			if (ui?.hasUI) ui.ui.setStatus("mox", text);
+		},
+		// Fired once, queued behind the current run: starts a turn when idle, waits when busy.
+		send: (cue) =>
+			pi.sendMessage(
+				{ customType: "mox", content: cue.message, display: true, details: { id: toRoman(cue.id), at: cue.at } },
+				{ triggerTurn: true, deliverAs: "followUp" },
+			),
+		onError: (error, cue) => notify(`·MOX· could not deliver ${toRoman(cue.id)}: ${error instanceof Error ? error.message : String(error)}`, "error"),
+	});
+
+	pi.registerMessageRenderer("mox", (message, renderOptions) => {
+		const at = (message.details as { at?: unknown } | undefined)?.at;
+		const content = typeof message.content === "string" ? message.content : message.content.map((part) => (part.type === "text" ? part.text : "")).join("");
+		return new options.Text(renderMoxText(content, typeof at === "number" ? at : undefined), renderOptions.outputPad ?? 1, 0);
+	});
+
+	pi.registerCommand("mox", {
+		description: "Schedule a message for the agent: /mox <10:30|+2h15m> <message>, /mox list, /mox cancel <id>",
+		getArgumentCompletions: (prefix) => completeMoxArgs(prefix, mox),
+		handler: async (args, ctx) => {
+			use(ctx);
+			runMoxCommand(args, { ctx: { hasUI: ctx.hasUI, ui: { notify } }, mox, now });
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		use(ctx);
+	});
+
+	// Cues live in memory only: a closed session keeps none of them.
+	pi.on("session_shutdown", async () => {
+		mox.shutdown();
+		ui = undefined;
+	});
+}