pi-roundtable 0.7.10 → 0.7.11

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.11] - 2026-10-03
+
+### Added
+
+- Precheck scripts: agents may write a schedule's precheck themselves. `schedule_create` and `schedule_update` take `precheck_script`, a JavaScript module of at most `PRECHECK_SCRIPT_CHARS` (8,000) characters with a default export, parsed but never run when it is set; a schedule has a `precheck` or a `precheck_script`, and setting one removes the other. The core never runs a script: a `PrecheckScriptRunner` registered with `PRECHECKS.useScriptRunner` (`scriptRunner` reads it) runs it with a `PrecheckScriptContext` (the schedule, `firedAt`, `signal`, the host's `timeZone`, and `today`), and its `describe` (given a `PrecheckScope`) tells the model what a script may call; `schedule_list` shows it and a schedule's script. Without a runner, the tools neither take nor mention scripts, and a stored script wakes the turn with `### Precheck failed: script`. `Schedule`, `NewSchedule`, and `ScheduleChange` gain `precheckScript`; the `schedules` table gains a nullable `precheck_script` column through the new `schedules-precheck-script` migration. `scheduleToolSpecs` takes `precheckScripts`.
+- `pi-roundtable/testing`: `fakeScriptRunner` (`fakeScriptRunner(answer, options?)`), with the types `FakeScriptAnswer` and `FakeScriptRunner`.
+- `PrecheckScope` carries `tier`: the script's creator's tier when it runs, the asker's when `schedule_list` describes it, so a runner may grant lower tiers less. A script may export its default as `export { check as default }`. The store itself keeps a schedule's `precheck` and `precheckScript` apart. `schedule_list` waits at most 10 seconds for the runner's `describe`.
+
+### Changed
+
+- Stopping the scheduler aborts running prechecks (their `signal` fires) and waits up to 15 seconds for them to settle, so a sandboxed script's container is removed before the host exits; a precheck that ends after the stop starts no turn and records `skipped: the host stopped during its precheck`.
+- Behavior change: `PrecheckRegistry` gains `useScriptRunner` and `scriptRunner`, so a host that provides `PRECHECKS` with a registry of its own must add them.
+- pi-roundtable-sandbox: `precheckScriptRunner` runs each script in a sealed container; see its changelog.
+
 ## [0.7.10] - 2026-10-03
 
 ### Added

package/docs/plugins.md

@@ -167,7 +167,7 @@ The built-in plugins provide these, from the main entry:
 | `AGENTS` | `AgentServer` | `agent-server` | The `team` (`AgentTeam`), the read-only `directory` (`AgentDirectory`), the `runtime` every agent turn runs on, `approvals` (whether the owner's reply approves held actions), and `avatars` (`AvatarStudio`) |
 | `SKILLS` | `SkillRegistry` | `skills` (an addon) | What agents carry: `carried`, `carriedNames`, `describeCarried`, `catalog`, `list`, `linkedFrom`, `checkRegistered`, `link`, `attach` |
 | `SCHEDULES` | `ScheduleStore` | `schedule-store` | The stored schedules: `create`, `get`, `forChannel`, `all`, `update`, `remove`, `due`, `claim`, `recordStatus` |
-| `PRECHECKS` | `PrecheckRegistry` | `prechecks` | The host's named [prechecks](#prechecks-wake-a-schedule-only-when-it-has-work): `register`, `get`, `list` |
+| `PRECHECKS` | `PrecheckRegistry` | `prechecks` | The host's named [prechecks](#prechecks-wake-a-schedule-only-when-it-has-work): `register`, `get`, `list`; and the runner of agents' precheck scripts: `useScriptRunner`, `scriptRunner` |
 | `MEMORY` | `MemoryStore` | `memory` (an addon) | `forSpeaker(id)` gives that speaker's `SpeakerMemory`: `list`, `forPrompt`, `add`, `search`, `update`, `removeById`, `remove`; `MEMORY_KINDS` is `core`, `note`, `event` |
 | `BACKGROUND_TURNS` | `BackgroundTurns` | `modules` | Turns nobody wrote: `runScheduled`, `runDelegated`, `runErrorReport` |
 | `DELEGATION` | `Delegator` | `modules` | `start(request)` a background task, `runningChannels()`, `idle()` |
@@ -800,6 +800,19 @@ export function recoveryPrecheck(read: () => Promise<RecoveryReading>) {
 ```
 <!-- /example -->
 
+##### Precheck scripts: prechecks the agent writes
+
+A host can also let agents write a schedule's precheck themselves, so a new check needs no change to the host.
+The core stores the script with the schedule and decides with it exactly as with a named precheck, but it never runs a script itself: a `PrecheckScriptRunner` does, registered once with `services.get(PRECHECKS).useScriptRunner(runner)`.
+pi-roundtable-sandbox's `precheckScriptRunner` runs each script in a sealed container whose only way out is the MCP tools the host grants for that schedule; see its README.
+
+- `schedule_create` and `schedule_update` take `precheck_script`, a JavaScript module of at most `PRECHECK_SCRIPT_CHARS` (8,000) characters with a default export; it is parsed, never run, when it is set. A schedule has a `precheck` or a `precheck_script`; setting one removes the other, and `null` removes either.
+- The runner's `run(script, context)` gets the `PrecheckScriptContext`: the schedule, `firedAt`, `signal`, the host's `timeZone`, and `today`, the date there. Its answer is checked like a named precheck's, and its finding is named `script`.
+- `describe({ channel, target, tier })` (a `PrecheckScope`) tells the model how to write one and what it may call there; `schedule_list` shows it, waiting at most 10 seconds. `tier` is the asker's there and the script's creator's when it runs, so a runner may grant lower tiers less.
+- When the host stops, the scheduler aborts running scripts and waits up to 15 seconds for the runner to clean up; a precheck that ends then starts no turn.
+- Without a runner, the tools neither take nor mention `precheck_script`, a script is refused with the registered names, and a schedule that already has one wakes with `### Precheck failed: script`, never a silent skip.
+
+
 ### `migrations` and `context.database()`: tables of your own
 
 Declare `migrations` on the plugin object.
@@ -2135,6 +2148,7 @@ Call `useTestLocale()` after a test changes the process-wide locale or time zone
 Use `partial<Port>({ ... })` to stand in for a port your code takes as an argument.
 It provides the members you give it and throws an error naming any missing member you read, so the test needs no `as unknown as Port` cast.
 `fakePrecheck(name, answer, { description?, timeoutMs? })` is a precheck that answers `answer` (a `PrecheckResult`, an `Error` it throws, or a function of its context) and records each context in `calls`; `fakePrechecks(...prechecks)` is a real in-memory `PrecheckRegistry` with them registered, which a test gives a plugin as `servicePair(PRECHECKS, registry)` and reads back with `registry.get(name)`.
+`fakeScriptRunner(answer, { describe?, timeoutMs? })` is a `PrecheckScriptRunner` that runs nothing and answers `answer` (a result, an `Error` it throws, or a function of the script and its context), recording each call in `calls`; give it to `registry.useScriptRunner`.
 `fakeDiscord({ ownerId?, rootCommand? })` is the `DISCORD` service for a plugin that adds slash commands: give it as `services: [discord.service]`, read what the plugin added with `discord.added()`, and compose the tree Discord would get with `discord.compose()`.
 Only `commands` and `guard` are given; a plugin that reads another member of `DISCORD` in a test gives its own with `servicePair(DISCORD, { ... })`.
 
@@ -2507,6 +2521,10 @@ Import from the entries listed below; source area files are internal.
 | `PrecheckFinding` | `pi-roundtable` | type |
 | `PrecheckRegistry` | `pi-roundtable` | type |
 | `PrecheckResult` | `pi-roundtable` | type |
+| `PrecheckScope` | `pi-roundtable` | type |
+| `PrecheckScriptContext` | `pi-roundtable` | type |
+| `PrecheckScriptRunner` | `pi-roundtable` | type |
+| `PRECHECK_SCRIPT_CHARS` | `pi-roundtable` | value |
 | `SKILLS` | `pi-roundtable` | value |
 | `Schedule` | `pi-roundtable` | type |
 | `ScheduleChange` | `pi-roundtable` | type |
@@ -2585,6 +2603,9 @@ Import from the entries listed below; source area files are internal.
 | `fakePrechecks` | `pi-roundtable/testing` | value |
 | `FakePrecheck` | `pi-roundtable/testing` | type |
 | `FakePrecheckAnswer` | `pi-roundtable/testing` | type |
+| `fakeScriptRunner` | `pi-roundtable/testing` | value |
+| `FakeScriptAnswer` | `pi-roundtable/testing` | type |
+| `FakeScriptRunner` | `pi-roundtable/testing` | type |
 | `fakeThreads` | `pi-roundtable/testing` | value |
 | `openTestStore` | `pi-roundtable/testing` | value |
 | `servicePair` | `pi-roundtable/testing` | value |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.10",
+	"version": "0.7.11",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

package/src/core/discord/schedule-commands.ts

@@ -78,7 +78,9 @@ function section(schedule: Schedule, label: TargetLabel): string {
 		text.scheduleSetBy(plain(schedule.createdByName), last),
 		...(schedule.precheck
 			? [text.schedulePrecheck(plain(schedule.precheck))]
-			: []),
+			: schedule.precheckScript
+				? [text.schedulePrecheckScript(schedule.precheckScript.length)]
+				: []),
 		`-# ${plain(prompt)}`,
 	].join("\n");
 }

package/src/core/i18n/schedules.ts

@@ -49,6 +49,8 @@ export function schedulesEn(ctx: CatalogContext) {
 		scheduleSetBy: (name: string, lastRun: string) =>
 			`Set by ${name}${lastRun}`,
 		schedulePrecheck: (name: string) => `Checked first by precheck ${name}`,
+		schedulePrecheckScript: (chars: number) =>
+			`Checked first by its own precheck script (${chars} characters)`,
 		schedulePrecheckNote: (id: number, title: string, note: string) =>
 			`-# Schedule #${id} ${title}, skipped by its precheck: ${note.replace(/\n+/g, "\n-# ")}`,
 		scheduleChoice: (id: number, title: string, recurrence: string) =>
@@ -91,6 +93,8 @@ export function schedulesZhTW(
 		scheduleSetBy: (name: string, lastRun: string) =>
 			`由 ${name} 設定${lastRun}`,
 		schedulePrecheck: (name: string) => `先由預檢 ${name} 判斷`,
+		schedulePrecheckScript: (chars: number) =>
+			`先由自訂的預檢腳本判斷（${chars} 字元）`,
 		schedulePrecheckNote: (id: number, title: string, note: string) =>
 			`-# 排程 #${id} ${title} 經預檢略過：${note.replace(/\n+/g, "\n-# ")}`,
 		scheduleChoice: (id: number, title: string, recurrence: string) =>

package/src/core/modules/schedules/prechecks.ts

@@ -1,9 +1,19 @@
+import { parse } from "@babel/parser";
+import type { ChannelKey } from "../../domain/conversation.ts";
+import { ScheduleError } from "../../domain/errors.ts";
 import { PluginError } from "../../errors.ts";
+import type { Tier } from "../../speakers.ts";
 import type { Schedule } from "./schedule-store.ts";
 
 /** How long a precheck may run before it counts as failed, unless it sets its own `timeoutMs`. */
 export const PRECHECK_TIMEOUT_MS = 60_000;
 
+/** The longest precheck script a schedule may carry, in characters. */
+export const PRECHECK_SCRIPT_CHARS = 8_000;
+
+/** What a finding names a schedule's own script by, in its heading and status. */
+export const SCRIPT_PRECHECK = "script";
+
 /** A precheck name: lower-case letters, digits, `.`, `_`, and `-`, starting with a letter or digit. */
 const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 
@@ -25,7 +35,7 @@ export interface PrecheckContext {
 	/** The due schedule, already moved to its next run (or deleted, when it runs once). */
 	schedule: Schedule;
 	firedAt: Date;
-	/** Aborted when the precheck runs out of time; its answer is then ignored. */
+	/** Aborted when the precheck runs out of time or the host stops; its answer is then ignored. */
 	signal: AbortSignal;
 }
 
@@ -45,13 +55,57 @@ export interface Precheck {
 	run(context: PrecheckContext): PrecheckResult | Promise<PrecheckResult>;
 }
 
-/** The host's prechecks, by name. Provided as `PRECHECKS` by the `prechecks` plugin. */
+/** Whose schedule a script is for: the runner decides what such a script may reach from it. */
+export interface PrecheckScope {
+	channel: ChannelKey;
+	/** The schedule's background target, such as the owner's. */
+	target: string;
+	/**
+	 * The tier of whoever set the script: its creator's when it runs, the asker's when schedule_list
+	 * describes it; absent when the asker's is unknown. A runner may grant lower tiers less.
+	 */
+	tier?: Tier;
+}
+
+/** What a schedule's precheck script runs with when its schedule falls due. */
+export interface PrecheckScriptContext extends PrecheckContext {
+	/** The host's IANA time zone, such as `Asia/Taipei`. */
+	timeZone: string;
+	/** The date in that zone when it fired, `YYYY-MM-DD`, so a script never reads a UTC date by mistake. */
+	today: string;
+}
+
+/**
+ * Runs the precheck scripts agents write for their schedules, isolated from the host: the core
+ * stores, checks, and schedules them but never runs one itself. Provided by a sandbox, such as
+ * pi-roundtable-sandbox's `precheckScriptRunner`, through `PRECHECKS.useScriptRunner`.
+ */
+export interface PrecheckScriptRunner {
+	/** Runs one script; its answer is checked like a host precheck's, and a throw wakes the turn with the error. */
+	run(
+		script: string,
+		context: PrecheckScriptContext,
+	): PrecheckResult | Promise<PrecheckResult>;
+	/** How long a script may run; default 60 seconds. A timeout counts as a throw. */
+	timeoutMs?: number;
+	/**
+	 * How to write a script for a schedule in this scope, and what it may call there, shown to the
+	 * model by schedule_list.
+	 */
+	describe(scope: PrecheckScope): string | Promise<string>;
+}
+
+/** The host's prechecks, by name, and the runner of agents' precheck scripts. Provided as `PRECHECKS` by the `prechecks` plugin. */
 export interface PrecheckRegistry {
 	/** Adds a precheck; throws PluginError for a bad or repeated name, an empty description, or a bad timeout. */
 	register(precheck: Precheck): void;
 	get(name: string): Precheck | undefined;
 	/** Every registered precheck, by name. */
 	list(): readonly Precheck[];
+	/** Lets agents attach scripts of their own, run by this runner; throws PluginError when one is set already. */
+	useScriptRunner(runner: PrecheckScriptRunner): void;
+	/** The runner of precheck scripts; undefined when no sandbox provides one, and then no script is accepted. */
+	scriptRunner(): PrecheckScriptRunner | undefined;
 }
 
 /** What came of a precheck that let the turn run, carried into the turn's text. */
@@ -71,7 +125,30 @@ export type PrecheckOutcome =
  */
 export function memoryPrecheckRegistry(): PrecheckRegistry {
 	const prechecks = new Map<string, Precheck>();
+	let runner: PrecheckScriptRunner | undefined;
 	return {
+		useScriptRunner(given) {
+			if (runner)
+				throw new PluginError(
+					"a precheck script runner is set already; register one sandbox to run scripts.",
+				);
+			if (
+				typeof given?.run !== "function" ||
+				typeof given.describe !== "function"
+			)
+				throw new PluginError(
+					"a precheck script runner needs run and describe functions.",
+				);
+			if (
+				given.timeoutMs !== undefined &&
+				!(Number.isInteger(given.timeoutMs) && given.timeoutMs > 0)
+			)
+				throw new PluginError(
+					`a precheck script runner's timeoutMs must be a positive whole number of milliseconds; got ${String(given.timeoutMs)}.`,
+				);
+			runner = given;
+		},
+		scriptRunner: () => runner,
 		register(precheck) {
 			const { name, description, timeoutMs, run } = precheck ?? {};
 			if (typeof name !== "string" || !NAME.test(name))
@@ -103,6 +180,47 @@ export function memoryPrecheckRegistry(): PrecheckRegistry {
 	};
 }
 
+/**
+ * Checks a precheck script without running it: a JavaScript module within the size limit whose
+ * default export is what the runner calls. Throws ScheduleError with what to fix.
+ */
+export function checkPrecheckScript(script: unknown): string {
+	if (typeof script !== "string" || !script.trim())
+		throw new ScheduleError(
+			"precheck_script must be a JavaScript module with a default export",
+		);
+	if (script.length > PRECHECK_SCRIPT_CHARS)
+		throw new ScheduleError(
+			`precheck_script is ${script.length} characters; keep it within ${PRECHECK_SCRIPT_CHARS}`,
+		);
+	let program: ReturnType<typeof parse>["program"];
+	try {
+		program = parse(script, {
+			sourceType: "module",
+			errorRecovery: false,
+		}).program;
+	} catch (error) {
+		throw new ScheduleError(
+			`precheck_script does not parse as a JavaScript module: ${errorText(error)}`,
+		);
+	}
+	const exportsDefault = program.body.some(
+		(node) =>
+			node.type === "ExportDefaultDeclaration" ||
+			(node.type === "ExportNamedDeclaration" &&
+				node.specifiers.some((specifier) =>
+					specifier.exported.type === "Identifier"
+						? specifier.exported.name === "default"
+						: specifier.exported.value === "default",
+				)),
+	);
+	if (!exportsDefault)
+		throw new ScheduleError(
+			"precheck_script needs a default export: export default async (context) => ({ wake: false, note }) or ({ wake: true, context })",
+		);
+	return script;
+}
+
 function errorText(error: unknown): string {
 	return error instanceof Error ? error.message || error.name : String(error);
 }
@@ -128,10 +246,17 @@ function decided(result: unknown): PrecheckOutcome {
 export async function runPrecheck(
 	precheck: Precheck,
 	context: Omit<PrecheckContext, "signal">,
+	options: {
+		/** Aborts the run early, such as when the host stops; it then fails with `stopped`. */
+		signal?: AbortSignal;
+		/** Receives the run itself, which may outlast the answer after a timeout, so a caller can await its cleanup. */
+		settled?: (run: Promise<unknown>) => void;
+	} = {},
 ): Promise<PrecheckOutcome> {
 	const timeoutMs = precheck.timeoutMs ?? PRECHECK_TIMEOUT_MS;
 	const abort = new AbortController();
 	let timer: ReturnType<typeof setTimeout> | undefined;
+	let stop: (() => void) | undefined;
 	const timeout = new Promise<PrecheckOutcome>((resolve) => {
 		timer = setTimeout(() => {
 			abort.abort();
@@ -140,6 +265,12 @@ export async function runPrecheck(
 				error: `it did not answer within ${timeoutMs / 1000} seconds`,
 			});
 		}, timeoutMs);
+		stop = () => {
+			abort.abort();
+			resolve({ kind: "failed", error: "stopped: the host is shutting down" });
+		};
+		if (options.signal?.aborted) stop();
+		else options.signal?.addEventListener("abort", stop, { once: true });
 	});
 	const answer = (async (): Promise<PrecheckOutcome> => {
 		try {
@@ -148,9 +279,11 @@ export async function runPrecheck(
 			return { kind: "failed", error: `it threw: ${errorText(error)}` };
 		}
 	})();
+	options.settled?.(answer);
 	try {
 		return await Promise.race([answer, timeout]);
 	} finally {
 		clearTimeout(timer);
+		if (stop) options.signal?.removeEventListener("abort", stop);
 	}
 }

package/src/core/modules/schedules/schedule-store.ts

@@ -1,6 +1,7 @@
 import type { SQL } from "bun";
 import type { Migration } from "../../db/migrations.ts";
 import type { ChannelKey } from "../../domain/conversation.ts";
+import { ScheduleError } from "../../domain/errors.ts";
 import type { ScheduleStore } from "../../services.ts";
 import type { Tier } from "../../speakers.ts";
 import type { Recurrence } from "./recurrence.ts";
@@ -21,6 +22,8 @@ export interface Schedule {
 	createdAt: Date;
 	/** The name of the precheck the host runs before its turn; absent, the turn always runs. */
 	precheck?: string;
+	/** The precheck script an agent wrote for it, run in the host's sandbox; a schedule has a name or a script, not both. */
+	precheckScript?: string;
 	lastRun?: Date;
 	lastStatus?: string;
 }
@@ -37,6 +40,8 @@ export interface NewSchedule {
 	createdTier: Tier;
 	/** A registered precheck's name, run before each turn. */
 	precheck?: string;
+	/** A precheck script, run in the host's sandbox before each turn; not with `precheck`. */
+	precheckScript?: string;
 }
 
 export interface ScheduleChange {
@@ -46,6 +51,8 @@ export interface ScheduleChange {
 	nextRun?: Date;
 	/** A registered precheck's name to run before each turn; null removes the schedule's precheck. */
 	precheck?: string | null;
+	/** A precheck script to run before each turn; null removes it. */
+	precheckScript?: string | null;
 }
 
 interface Row {
@@ -62,6 +69,7 @@ interface Row {
 	created_tier: Tier;
 	created_at: Date;
 	precheck: string | null;
+	precheck_script: string | null;
 	last_run: Date | null;
 	last_status: string | null;
 }
@@ -81,6 +89,7 @@ function toSchedule(row: Row): Schedule {
 		createdTier: row.created_tier,
 		createdAt: row.created_at,
 		...(row.precheck ? { precheck: row.precheck } : {}),
+		...(row.precheck_script ? { precheckScript: row.precheck_script } : {}),
 		...(row.last_run ? { lastRun: row.last_run } : {}),
 		...(row.last_status ? { lastStatus: row.last_status } : {}),
 	};
@@ -120,7 +129,7 @@ export class PgScheduleStore implements ScheduleStore {
 		},
 	};
 
-	/** The table, then the precheck each schedule may name; schedules made before prechecks have none. */
+	/** The table, then the precheck each schedule may name or carry; schedules made before prechecks have none. */
 	static migrations(): Migration[] {
 		return [
 			PgScheduleStore.migration,
@@ -130,6 +139,12 @@ export class PgScheduleStore implements ScheduleStore {
 					await sql`ALTER TABLE schedules ADD COLUMN IF NOT EXISTS precheck text`;
 				},
 			},
+			{
+				name: "schedules-precheck-script",
+				up: async (sql) => {
+					await sql`ALTER TABLE schedules ADD COLUMN IF NOT EXISTS precheck_script text`;
+				},
+			},
 		];
 	}
 
@@ -139,13 +154,17 @@ export class PgScheduleStore implements ScheduleStore {
 	}
 
 	async create(schedule: NewSchedule): Promise<Schedule> {
+		if (schedule.precheck && schedule.precheckScript)
+			throw new ScheduleError(
+				"a schedule has a precheck or a precheck script, not both",
+			);
 		const rows: Row[] = await this.#sql`
 			INSERT INTO schedules (channel_key, mode, title, prompt, recurrence, next_run,
-				created_by_id, created_by_name, created_tier, precheck)
+				created_by_id, created_by_name, created_tier, precheck, precheck_script)
 			VALUES (${schedule.channel}, ${schedule.target}, ${schedule.title}, ${schedule.prompt},
 				${JSON.stringify(schedule.recurrence)}, ${schedule.nextRun},
 				${schedule.createdById}, ${schedule.createdByName}, ${schedule.createdTier},
-				${schedule.precheck ?? null})
+				${schedule.precheck ?? null}, ${schedule.precheckScript ?? null})
 			RETURNING *`;
 		const [row] = rows;
 		if (!row) throw new Error("the schedule insert returned no row");
@@ -178,13 +197,29 @@ export class PgScheduleStore implements ScheduleStore {
 	): Promise<Schedule | undefined> {
 		const current = await this.get(id);
 		if (!current || current.channel !== channel) return undefined;
+		if (change.precheck && change.precheckScript)
+			throw new ScheduleError(
+				"a schedule has a precheck or a precheck script, not both",
+			);
+		// Setting one removes the other, so the scheduler never has to pick.
+		const precheck = change.precheckScript
+			? null
+			: change.precheck === undefined
+				? (current.precheck ?? null)
+				: change.precheck;
+		const precheckScript = change.precheck
+			? null
+			: change.precheckScript === undefined
+				? (current.precheckScript ?? null)
+				: change.precheckScript;
 		const rows: Row[] = await this.#sql`
 			UPDATE schedules SET
 				title = ${change.title ?? current.title},
 				prompt = ${change.prompt ?? current.prompt},
 				recurrence = ${JSON.stringify(change.recurrence ?? current.recurrence)},
 				next_run = ${change.nextRun ?? current.nextRun},
-				precheck = ${change.precheck === undefined ? (current.precheck ?? null) : change.precheck}
+				precheck = ${precheck},
+				precheck_script = ${precheckScript}
 			WHERE id = ${id}
 			RETURNING *`;
 		return rows[0] ? toSchedule(rows[0]) : undefined;

package/src/core/modules/schedules/schedule-tools.ts

@@ -6,7 +6,12 @@ import type { ScheduleStore } from "../../services.ts";
 import type { ScheduleToolName } from "../../shared/schedule-tools.ts";
 import { type Tier, tierAtLeast } from "../../speakers.ts";
 import { timeZone, zonedStamp } from "../../time.ts";
-import type { PrecheckFinding, PrecheckRegistry } from "./prechecks.ts";
+import {
+	checkPrecheckScript,
+	PRECHECK_SCRIPT_CHARS,
+	type PrecheckFinding,
+	type PrecheckRegistry,
+} from "./prechecks.ts";
 import {
 	describeRecurrence,
 	nextRun,
@@ -18,6 +23,8 @@ import type { Schedule } from "./schedule-store.ts";
 
 const TITLE_CHARS = 80;
 const LIST_PROMPT_PREVIEW = 200;
+/** How long schedule_list waits for the script runner to say what a script may call. */
+const DESCRIBE_TIMEOUT_MS = 10_000;
 const DAY_MS = 86_400_000;
 
 export interface ScheduleToolContext {
@@ -31,8 +38,12 @@ export interface ScheduleToolContext {
 	/** Who asked, recorded on created schedules; a scheduled run speaks for its creator. */
 	author: { id: string; name: string; tier?: Tier };
 	now: Date;
-	/** The host's prechecks a schedule may name; without them, none can be attached. */
-	prechecks?: Pick<PrecheckRegistry, "get" | "list">;
+	/**
+	 * The host's prechecks a schedule may name, and the runner of the scripts it may carry instead;
+	 * without them, none can be attached.
+	 */
+	prechecks?: Pick<PrecheckRegistry, "get" | "list"> &
+		Partial<Pick<PrecheckRegistry, "scriptRunner">>;
 }
 
 /** The limits of the context's target; a target without them may not schedule. */
@@ -84,11 +95,57 @@ function precheckName(ctx: ScheduleToolContext, value: unknown): string {
 	return name;
 }
 
-/** The prechecks a schedule may name, for schedule_list; empty when the host registers none. */
-function precheckCatalog(ctx: ScheduleToolContext): string {
+/** A precheck script the host's sandbox runs; refused when the host has no runner for scripts. */
+function precheckScript(ctx: ScheduleToolContext, value: unknown): string {
+	if (!ctx.prechecks?.scriptRunner?.()) {
+		const names = (ctx.prechecks?.list() ?? []).map((p) => p.name);
+		throw new ScheduleError(
+			`this host runs no precheck scripts; ${names.length ? `attach a registered precheck instead: ${names.join(", ")}` : "it registers no prechecks either"}`,
+		);
+	}
+	return checkPrecheckScript(value);
+}
+
+/** The prechecks a schedule may name or write, for schedule_list; empty when the host offers neither. */
+async function precheckCatalog(ctx: ScheduleToolContext): Promise<string> {
 	const all = ctx.prechecks?.list() ?? [];
-	if (all.length === 0) return "";
-	return `\n\nPrechecks you can attach with precheck on schedule_create or schedule_update; the host runs one before each turn and wakes you only when it finds something:\n${all.map((p) => `- ${p.name}: ${p.description.replace(/\n/g, " ")}`).join("\n")}`;
+	const runner = ctx.prechecks?.scriptRunner?.();
+	const named =
+		all.length === 0
+			? ""
+			: `\n\nPrechecks you can attach with precheck on schedule_create or schedule_update; the host runs one before each turn and wakes you only when it finds something:\n${all.map((p) => `- ${p.name}: ${p.description.replace(/\n/g, " ")}`).join("\n")}`;
+	if (!runner) return named;
+	// The list still answers when the host cannot say, or is slow to say, what a script may reach here.
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const late = new Promise<string>((resolve) => {
+		timer = setTimeout(
+			() => resolve("it did not answer in time"),
+			DESCRIBE_TIMEOUT_MS,
+		);
+	});
+	const described = Promise.resolve()
+		.then(() =>
+			runner.describe({
+				channel: ctx.channel,
+				target: ctx.target.name,
+				...(ctx.author.tier ? { tier: ctx.author.tier } : {}),
+			}),
+		)
+		.then(
+			(text) => ({ text }),
+			(error: unknown) => ({
+				error: error instanceof Error ? error.message : String(error),
+			}),
+		);
+	const answer = await Promise.race([
+		described,
+		late.then((error) => ({ error })),
+	]).finally(() => clearTimeout(timer));
+	const guide =
+		"text" in answer
+			? answer.text
+			: `The host could not say what a script may call here (${answer.error}); a script set now may fail when it runs.`;
+	return `${named}\n\nYou can write a precheck of your own instead, with precheck_script on schedule_create or schedule_update (null removes it): a JavaScript module, at most ${PRECHECK_SCRIPT_CHARS} characters, that the host runs in a sandbox before each turn. A schedule has a precheck or a precheck_script, not both.\n${guide}`;
 }
 
 function hasTiming(input: Input): boolean {
@@ -121,7 +178,11 @@ function line(schedule: Schedule): string {
 		schedule.prompt.length > LIST_PROMPT_PREVIEW
 			? `${schedule.prompt.slice(0, LIST_PROMPT_PREVIEW)}…`
 			: schedule.prompt;
-	const precheck = schedule.precheck ? `; precheck ${schedule.precheck}` : "";
+	const precheck = schedule.precheck
+		? `; precheck ${schedule.precheck}`
+		: schedule.precheckScript
+			? `; precheck script (${schedule.precheckScript.length} characters)`
+			: "";
 	const last = schedule.lastRun
 		? `; last run ${zonedStamp(schedule.lastRun)} (${schedule.lastStatus ?? "?"})`
 		: "";
@@ -159,10 +220,16 @@ export async function callScheduleTool(
 			const title = text(input, "title", TITLE_CHARS);
 			const prompt = text(input, "prompt", limits.promptChars);
 			const [recurrence, next] = timing(ctx, input);
-			const precheck =
-				input.precheck === undefined || input.precheck === null
-					? undefined
-					: precheckName(ctx, input.precheck);
+			const given = (name: string) =>
+				input[name] !== undefined && input[name] !== null;
+			if (given("precheck") && given("precheck_script"))
+				throw new ScheduleError("give precheck or precheck_script, not both");
+			const precheck = given("precheck")
+				? precheckName(ctx, input.precheck)
+				: undefined;
+			const script = given("precheck_script")
+				? precheckScript(ctx, input.precheck_script)
+				: undefined;
 			const existing = await ctx.store.forChannel(ctx.channel);
 			if (existing.length >= limits.perChannel)
 				throw new ScheduleError(
@@ -179,21 +246,29 @@ export async function callScheduleTool(
 				createdByName: ctx.author.name,
 				createdTier: ctx.author.tier ?? "owner",
 				...(precheck ? { precheck } : {}),
+				...(script ? { precheckScript: script } : {}),
 			});
-			const checked = precheck ? `; precheck ${precheck} runs first` : "";
+			const checked = precheck
+				? `; precheck ${precheck} runs first`
+				: script
+					? "; its precheck script runs first"
+					: "";
 			return `Scheduled #${created.id} "${title}": ${describeRecurrence(recurrence)}, first run ${zonedStamp(next)} ${messages().zoneTime(timeZone())}${checked}.`;
 		}
 		case "schedule_list": {
 			if (input.id !== undefined) {
 				const schedule = await own(ctx, input);
-				return `${line(schedule).split("\n")[0]}\n\nPrompt:\n${schedule.prompt}`;
+				const script = schedule.precheckScript
+					? `\n\nPrecheck script:\n${schedule.precheckScript}`
+					: "";
+				return `${line(schedule).split("\n")[0]}\n\nPrompt:\n${schedule.prompt}${script}`;
 			}
 			const all = await ctx.store.forChannel(ctx.channel);
 			const listed =
 				all.length === 0
 					? "This channel has no schedules."
 					: `It is ${zonedStamp(ctx.now)} in ${messages().zoneName(timeZone())}.\n${all.map(line).join("\n")}`;
-			return `${listed}${precheckCatalog(ctx)}`;
+			return `${listed}${await precheckCatalog(ctx)}`;
 		}
 		case "schedule_update": {
 			const schedule = changeable(ctx, await own(ctx, input));
@@ -207,19 +282,35 @@ export async function callScheduleTool(
 				change.recurrence = recurrence;
 				change.nextRun = next;
 			}
-			// null removes the precheck; a name must be registered.
+			// null removes one; a name must be registered, and a script replaces a name and back.
+			if (
+				input.precheck !== undefined &&
+				input.precheck !== null &&
+				input.precheck_script !== undefined &&
+				input.precheck_script !== null
+			)
+				throw new ScheduleError("give precheck or precheck_script, not both");
 			if (input.precheck !== undefined)
 				change.precheck =
 					input.precheck === null ? null : precheckName(ctx, input.precheck);
+			if (input.precheck_script !== undefined)
+				change.precheckScript =
+					input.precheck_script === null
+						? null
+						: precheckScript(ctx, input.precheck_script);
+			if (change.precheck) change.precheckScript = null;
+			if (change.precheckScript) change.precheck = null;
 			if (Object.keys(change).length === 0)
 				throw new ScheduleError(
-					"give a title, prompt, timing, or precheck to change",
+					"give a title, prompt, timing, precheck, or precheck_script to change",
 				);
 			const updated = await ctx.store.update(ctx.channel, schedule.id, change);
 			if (!updated) throw new ScheduleError(`schedule #${schedule.id} is gone`);
 			const checked = updated.precheck
 				? `; precheck ${updated.precheck} runs first`
-				: "";
+				: updated.precheckScript
+					? "; its precheck script runs first"
+					: "";
 			return `Updated #${updated.id} "${updated.title}": ${describeRecurrence(updated.recurrence)}, next run ${zonedStamp(updated.nextRun)}${checked}.`;
 		}
 		case "schedule_cancel": {

package/src/core/modules/schedules/scheduler.ts

@@ -1,11 +1,14 @@
 import type { ScheduledOutcome } from "../../contract/channels.ts";
 import type { Logger } from "../../log.ts";
 import type { ScheduleStore } from "../../services.ts";
+import { timeZone, zonedStamp } from "../../time.ts";
 import {
+	type Precheck,
 	type PrecheckFinding,
 	type PrecheckOutcome,
 	type PrecheckRegistry,
 	runPrecheck,
+	SCRIPT_PRECHECK,
 } from "./prechecks.ts";
 import { nextRun } from "./recurrence.ts";
 import type { Schedule } from "./schedule-store.ts";
@@ -21,14 +24,18 @@ export interface ScheduledRunner {
 	): Promise<ScheduledOutcome>;
 }
 
+/** How long stop waits for running prechecks to clean up after aborting them. */
+export const PRECHECK_STOP_MS = 15_000;
+
 /** A run found this late, for example after the service was down, is skipped instead of run. */
 export const LATE_LIMIT_MS = 12 * 3_600_000;
 
 export interface SchedulerOptions {
 	store: Pick<ScheduleStore, "due" | "claim" | "recordStatus">;
 	runner: ScheduledRunner;
-	/** The host's prechecks; without them, a schedule that names one runs with that as its error. */
-	prechecks?: Pick<PrecheckRegistry, "get">;
+	/** The host's prechecks and script runner; without them, a schedule that has one runs with that as its error. */
+	prechecks?: Pick<PrecheckRegistry, "get"> &
+		Partial<Pick<PrecheckRegistry, "scriptRunner">>;
 	/** Posts a skipping precheck's note in the schedule's channel as the bot's own message, which starts no turn. */
 	notify?: (schedule: Schedule, note: string) => Promise<void>;
 	logger: Logger;
@@ -67,6 +74,9 @@ function precheckPrefix(finding: PrecheckFinding | undefined): string {
 export class Scheduler {
 	readonly #options: SchedulerOptions;
 	readonly #running = new Set<Promise<void>>();
+	/** Prechecks in flight, including their cleanup after a timeout, which stop waits for. */
+	readonly #prechecks = new Set<Promise<unknown>>();
+	readonly #stopping = new AbortController();
 	#timer: ReturnType<typeof setInterval> | undefined;
 	#ticking = false;
 
@@ -82,13 +92,33 @@ export class Scheduler {
 		void this.tick();
 	}
 
-	stop(): void {
+	/**
+	 * Stops checking, aborts running prechecks, and waits up to PRECHECK_STOP_MS for them to clean
+	 * up, so a sandboxed script never outlives the host. A turn already running is left to the
+	 * host's drain; no precheck that ends now starts one.
+	 */
+	async stop(): Promise<void> {
 		clearInterval(this.#timer);
+		this.#stopping.abort();
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const limit = new Promise<"late">((resolve) => {
+			timer = setTimeout(() => resolve("late"), PRECHECK_STOP_MS);
+		});
+		const settled = Promise.allSettled([...this.#prechecks]);
+		try {
+			if ((await Promise.race([settled, limit])) === "late")
+				this.#options.logger.warn(
+					{ prechecks: this.#prechecks.size },
+					"prechecks still cleaning up when the scheduler stopped",
+				);
+		} finally {
+			clearTimeout(timer);
+		}
 	}
 
 	/** Claims every due schedule and starts its run; runs continue after tick resolves. */
 	async tick(): Promise<void> {
-		if (this.#ticking) return;
+		if (this.#ticking || this.#stopping.signal.aborted) return;
 		this.#ticking = true;
 		const { store, logger } = this.#options;
 		try {
@@ -132,20 +162,26 @@ export class Scheduler {
 	async #fire(schedule: Schedule, firedAt: Date): Promise<void> {
 		const { runner, logger } = this.#options;
 		let finding: PrecheckFinding | undefined;
-		if (schedule.precheck) {
-			const decision = await this.#precheck(
-				schedule,
-				schedule.precheck,
-				firedAt,
-			);
+		const name =
+			schedule.precheck ??
+			(schedule.precheckScript ? SCRIPT_PRECHECK : undefined);
+		if (name) {
+			const decision = await this.#precheck(schedule, name, firedAt);
+			if (this.#stopping.signal.aborted) {
+				await this.#record(
+					schedule,
+					"skipped: the host stopped during its precheck",
+				);
+				return;
+			}
 			if (decision.kind === "skip") {
 				await this.#skip(schedule, decision.note);
 				return;
 			}
 			finding =
 				decision.kind === "wake"
-					? { precheck: schedule.precheck, context: decision.context }
-					: { precheck: schedule.precheck, error: decision.error };
+					? { precheck: name, context: decision.context }
+					: { precheck: name, error: decision.error };
 		}
 		logger.info(
 			{
@@ -163,19 +199,63 @@ export class Scheduler {
 		);
 	}
 
+	/**
+	 * The schedule's precheck: a registered one by name, or its script through the host's runner.
+	 * A script never runs in this process; without a runner it fails, and the turn still runs.
+	 */
+	#resolve(schedule: Schedule, firedAt: Date): Precheck | string {
+		const { prechecks } = this.#options;
+		if (schedule.precheck)
+			return (
+				prechecks?.get(schedule.precheck) ??
+				"no precheck of that name is registered"
+			);
+		const script = schedule.precheckScript ?? "";
+		const runner = prechecks?.scriptRunner?.();
+		if (!runner)
+			return "this host has no precheck script runner, so the script did not run";
+		const zone = timeZone();
+		return {
+			name: SCRIPT_PRECHECK,
+			description: "the schedule's own precheck script",
+			...(runner.timeoutMs === undefined
+				? {}
+				: { timeoutMs: runner.timeoutMs }),
+			run: (context) =>
+				runner.run(script, {
+					...context,
+					timeZone: zone,
+					today: zonedStamp(firedAt).slice(0, 10),
+				}),
+		};
+	}
+
 	/** Runs the schedule's precheck; a missing one fails like a throw, so the turn still runs. */
 	async #precheck(
 		schedule: Schedule,
 		name: string,
 		firedAt: Date,
 	): Promise<PrecheckOutcome> {
-		const { prechecks, logger } = this.#options;
+		const { logger } = this.#options;
 		let decision: PrecheckOutcome;
 		try {
-			const precheck = prechecks?.get(name);
-			decision = precheck
-				? await runPrecheck(precheck, { schedule, firedAt })
-				: { kind: "failed", error: "no precheck of that name is registered" };
+			const precheck = this.#resolve(schedule, firedAt);
+			decision =
+				typeof precheck === "string"
+					? { kind: "failed", error: precheck }
+					: await runPrecheck(
+							precheck,
+							{ schedule, firedAt },
+							{
+								signal: this.#stopping.signal,
+								settled: (run) => {
+									const tracked = run
+										.catch(() => undefined)
+										.finally(() => this.#prechecks.delete(tracked));
+									this.#prechecks.add(tracked);
+								},
+							},
+						);
 		} catch (error) {
 			decision = {
 				kind: "failed",

package/src/core/modules/schedules/schedules.ts

@@ -27,8 +27,9 @@ export interface OwnerSchedules {
 	 * messages for a conversation no chat surface carries, where a run could not be posted.
 	 */
 	channelFor: (channel: ChannelKey) => Promise<ChannelKey>;
-	/** The host's prechecks a schedule may name; without them, none can be attached. */
-	prechecks?: Pick<PrecheckRegistry, "get" | "list">;
+	/** The host's prechecks a schedule may name, and the runner of scripts it may carry; without them, none can be attached. */
+	prechecks?: Pick<PrecheckRegistry, "get" | "list"> &
+		Partial<Pick<PrecheckRegistry, "scriptRunner">>;
 }
 
 /** Finds another agent's channel, for reading its schedules; throws ScheduleError when there is none. */
@@ -65,6 +66,7 @@ export function schedulesExtension(
 	const defs = scheduleToolSpecs({
 		locale: activeLocale(),
 		timeZone: timeZone(),
+		precheckScripts: prechecks?.scriptRunner?.() !== undefined,
 	}).map((base) => {
 		const spec = agents ? withAgentOption(base) : base;
 		return {

package/src/core/shared/schedule-tools.ts

@@ -74,12 +74,33 @@ export interface ScheduleToolWording {
 	locale: Locale;
 	/** An IANA time zone, such as `Asia/Taipei`. */
 	timeZone: string;
+	/**
+	 * Whether the host runs agents' precheck scripts, so schedule_create and schedule_update take
+	 * `precheck_script`; without it they neither take nor mention one.
+	 */
+	precheckScripts?: boolean;
 }
 
 export function scheduleToolSpecs(
 	wording: ScheduleToolWording,
 ): readonly ScheduleToolSpec[] {
 	const zone = catalogFor(wording.locale).zoneTime(wording.timeZone);
+	const script = (cleared: boolean): Record<string, TSchema> =>
+		wording.precheckScripts
+			? {
+					precheck_script: Type.Optional(
+						cleared
+							? Type.Union([Type.String(), Type.Null()], {
+									description:
+										"A JavaScript module the host runs in a sandbox before each turn, as schedule_list explains; it replaces precheck. null removes it.",
+								})
+							: Type.String({
+									description:
+										"A JavaScript module the host runs in a sandbox before each turn, as schedule_list explains; instead of precheck.",
+								}),
+					),
+				}
+			: {};
 	return [
 		{
 			name: "schedule_create",
@@ -97,6 +118,7 @@ export function scheduleToolSpecs(
 							"The name of a precheck the host runs first, from schedule_list; you are woken only when it finds something.",
 					}),
 				),
+				...script(false),
 			}),
 		},
 		{
@@ -125,6 +147,7 @@ export function scheduleToolSpecs(
 							"A precheck's name from schedule_list to run first, or null to remove the schedule's precheck.",
 					}),
 				),
+				...script(true),
 			}),
 		},
 		{

package/src/core/testing/prechecks.ts

@@ -4,6 +4,9 @@ import {
 	type PrecheckContext,
 	type PrecheckRegistry,
 	type PrecheckResult,
+	type PrecheckScope,
+	type PrecheckScriptContext,
+	type PrecheckScriptRunner,
 } from "../modules/schedules/prechecks.ts";
 
 /** What a fake precheck answers: a result, an Error it throws, or a function of its context. */
@@ -43,6 +46,47 @@ export function fakePrecheck(
 	};
 }
 
+/** What a fake script runner answers: a result, an Error it throws, or a function of the script and its context. */
+export type FakeScriptAnswer =
+	| PrecheckResult
+	| Error
+	| ((
+			script: string,
+			context: PrecheckScriptContext,
+	  ) => PrecheckResult | Promise<PrecheckResult>);
+
+/** A precheck script runner for tests, which records every script it was asked to run. */
+export interface FakeScriptRunner extends PrecheckScriptRunner {
+	readonly calls: { script: string; context: PrecheckScriptContext }[];
+}
+
+/**
+ * A script runner that runs nothing: it answers as the test says, for
+ * `registry.useScriptRunner(fakeScriptRunner({ wake: false }))`. `describe` defaults to a line
+ * naming it a test runner.
+ */
+export function fakeScriptRunner(
+	answer: FakeScriptAnswer,
+	options: {
+		describe?: (scope: PrecheckScope) => string;
+		timeoutMs?: number;
+	} = {},
+): FakeScriptRunner {
+	const calls: FakeScriptRunner["calls"] = [];
+	return {
+		calls,
+		...(options.timeoutMs === undefined
+			? {}
+			: { timeoutMs: options.timeoutMs }),
+		describe: options.describe ?? (() => "A test script runner."),
+		run: async (script, context) => {
+			calls.push({ script, context });
+			if (answer instanceof Error) throw answer;
+			return typeof answer === "function" ? answer(script, context) : answer;
+		},
+	};
+}
+
 /**
  * A real in-memory precheck registry with the given prechecks registered, for a test that builds
  * a scheduler or schedule tools itself. It refuses what the host's refuses.

package/src/index.ts

@@ -132,8 +132,14 @@ export type {
 	PrecheckFinding,
 	PrecheckRegistry,
 	PrecheckResult,
+	PrecheckScope,
+	PrecheckScriptContext,
+	PrecheckScriptRunner,
+} from "./core/modules/schedules/prechecks.ts";
+export {
+	PRECHECK_SCRIPT_CHARS,
+	PRECHECK_TIMEOUT_MS,
 } from "./core/modules/schedules/prechecks.ts";
-export { PRECHECK_TIMEOUT_MS } from "./core/modules/schedules/prechecks.ts";
 export type {
 	Recurrence,
 	Weekday,

package/src/testing.ts

@@ -86,8 +86,14 @@ export { partial } from "./core/testing/partial.ts";
 export type {
 	FakePrecheck,
 	FakePrecheckAnswer,
+	FakeScriptAnswer,
+	FakeScriptRunner,
+} from "./core/testing/prechecks.ts";
+export {
+	fakePrecheck,
+	fakePrechecks,
+	fakeScriptRunner,
 } from "./core/testing/prechecks.ts";
-export { fakePrecheck, fakePrechecks } from "./core/testing/prechecks.ts";
 export type {
 	RecordedLog,
 	RecordingLogger,