pi-roundtable 0.26.1 → 0.26.2

package/src/core/agents/team-turn-types.ts

@@ -7,6 +7,7 @@ import type {
 	TurnResult,
 } from "../domain/conversation.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
+import type { IdentityService } from "../identity/identity-port.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
@@ -85,6 +86,12 @@ export interface TeamTurnsOptions {
 	changed(): void;
 	/** Where turns and team changes are reported for the plugins' handlers. */
 	events?: EventSink;
+	/**
+	 * The identity service, read when a kept agent message is replayed: its speaker runs again only
+	 * as a principal that still exists and is enabled, at no more than its tier now. Without one, the
+	 * stored speaker is kept.
+	 */
+	principals?: () => Pick<IdentityService, "speakerFor"> | undefined;
 	/** A thread for each message between agents; without it both go in the sender's channel. */
 	threads?: Pick<DispatchThreads, "open">;
 }
@@ -94,8 +101,29 @@ export interface TurnExtra {
 	attachments?: TurnAttachments;
 	confirmed?: boolean;
 	steerable?: boolean;
+	/** A person's message started it. */
+	byMessage?: boolean;
 	/** The owner started it by writing, or it delivers a report, so it may ask them on cards. */
 	interactive?: boolean;
+	/** No person waits on the answer, so an empty one is no failure. */
+	unattended?: boolean;
+	/** How long the turn may work, in ms, in place of the default; a schedule's own limit. */
+	timeLimitMs?: number;
+}
+
+/** The fields of `extra` that a turn request carries, left out where unset. */
+export function turnFlags(extra: TurnExtra) {
+	return {
+		...(extra.attachments ? { attachments: extra.attachments } : {}),
+		...(extra.confirmed ? { confirmed: true } : {}),
+		...(extra.steerable ? { steerable: true } : {}),
+		...(extra.byMessage ? { byMessage: true } : {}),
+		...(extra.interactive ? { interactive: true } : {}),
+		...(extra.unattended ? { unattended: true } : {}),
+		...(extra.timeLimitMs === undefined
+			? {}
+			: { timeLimitMs: extra.timeLimitMs }),
+	};
 }
 
 /** What the team's message and group collaborators need of the turns that own their state. */

package/src/core/agents/team-turns.ts

@@ -11,7 +11,7 @@ import { AgentError } from "../domain/errors.ts";
 import type { InterimPosts } from "../domain/interim.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import type { TurnProgress } from "../domain/progress.ts";
-import { replyBody } from "../presentation/reply-body.ts";
+import { isQuiet, replyBody } from "../presentation/reply-body.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { withReplyFiles } from "../reply-files.ts";
 import { endOf, settleTurn } from "../routing/settle-turn.ts";
@@ -28,9 +28,9 @@ import {
 	coordinatorOf,
 	discordIdOf,
 	discordKey,
-	homeScope,
 	keysOf,
 	roomScope,
+	scopeOf,
 } from "./team-keys.ts";
 import {
 	type Chain,
@@ -38,6 +38,7 @@ import {
 	type TeamTurnsOptions,
 	type TurnExtra,
 	type TurnHost,
+	turnFlags,
 } from "./team-turn-types.ts";
 
 export { MAX_CHAIN_MESSAGES, type TeamTurnsOptions };
@@ -95,8 +96,8 @@ export class TeamTurns {
 	}
 
 	/**
-	 * The owner's message in an agent's channel; call inside the channel's queue. `text`
-	 * carries the reference, `replyText` is what they typed.
+	 * The owner's message in an agent's channel; call inside its queue. `text` carries the
+	 * reference, `replyText` is what they typed.
 	 */
 	async answerOwner(
 		channel: ChannelKey,
@@ -106,7 +107,7 @@ export class TeamTurns {
 		attachments: TurnAttachments,
 	): Promise<TurnResult> {
 		const agent = this.#agentOf(channel);
-		const scope = this.#scopeOf(agent, channel);
+		const scope = scopeOf(agent, channel);
 		const pending = await this.#options.runtime().heldActions(scope.session);
 		const confirmed =
 			pending !== undefined &&
@@ -122,29 +123,31 @@ export class TeamTurns {
 				attachments,
 				confirmed,
 				steerable: true,
+				byMessage: true,
 				interactive: true,
 			},
 		);
 	}
 
-	/**
-	 * A turn in an agent's channel that no owner message started; call inside its queue. A report
-	 * turn is interactive: it may ask the owner on cards there.
-	 */
+	/** A turn no owner message started; call inside its queue. A report turn is interactive. */
 	answerBackground(
 		channel: ChannelKey,
 		speaker: Speaker,
 		text: string,
 		interactive = false,
+		timeLimitMs?: number,
 	): Promise<TurnResult> {
 		const agent = this.#agentOf(channel);
 		return this.#turn(
 			agent,
-			this.#scopeOf(agent, channel),
+			scopeOf(agent, channel),
 			channel,
 			text,
 			{ messages: 0, speaker },
-			interactive ? { interactive: true } : {},
+			{
+				...(interactive ? { interactive: true } : { unattended: true }),
+				...(timeLimitMs === undefined ? {} : { timeLimitMs }),
+			},
 		);
 	}
 
@@ -190,13 +193,6 @@ export class TeamTurns {
 		return agent;
 	}
 
-	/** The agent's own conversation in the channel: its Discord channel's, or its room's. */
-	#scopeOf(agent: Agent, channel: ChannelKey): AgentTurnScope {
-		return discordIdOf(channel) === undefined
-			? roomScope(agent, channel)
-			: homeScope(agent);
-	}
-
 	/**
 	 * Runs one agent turn and posts its reply, or a failure notice, in `postTo` under the
 	 * agent's name. Never rejects.
@@ -216,6 +212,9 @@ export class TeamTurns {
 		this.#chains.set(scope.session, chain);
 		this.#posting.set(scope.session, postTo);
 		this.#working.set(agent.name, postTo);
+		// A message to the agent lands where it last ran a turn; a group round is none.
+		if (!scope.group)
+			this.#options.store.conversations.keep(agent.name, postTo, logger);
 		this.#active(agent.name, scope.group);
 		const turn = {
 			agent: agent.name,
@@ -236,10 +235,7 @@ export class TeamTurns {
 							channel: postTo,
 							selection: this.#options.selection(scope),
 							text,
-							...(extra.attachments ? { attachments: extra.attachments } : {}),
-							...(extra.confirmed ? { confirmed: true } : {}),
-							...(extra.steerable ? { steerable: true } : {}),
-							...(extra.interactive ? { interactive: true } : {}),
+							...turnFlags(extra),
 							agent: scope,
 							speaker: chain.speaker,
 							...(interim ? { interim } : {}),
@@ -266,7 +262,12 @@ export class TeamTurns {
 					"agent turn failed",
 				);
 			}
-			await this.#post(postTo, this.#current(agent), replyBody(result));
+			if (isQuiet(result))
+				logger.info(
+					{ agent: agent.name, channel: postTo },
+					"unattended turn had nothing to say; nothing posted",
+				);
+			else await this.#post(postTo, this.#current(agent), replyBody(result));
 		} catch (error) {
 			logger.error({ agent: agent.name, err: error }, "agent reply not posted");
 		} finally {
@@ -459,8 +460,18 @@ export class TeamTurns {
 		await this.#post(home, coordinator, { chunks: splitReply(text) });
 	}
 
-	message(caller: AgentTurnScope, to: string, text: string): string {
-		return this.#messages.message(caller, to, text);
+	message(...args: Parameters<AgentMessages["message"]>): string {
+		return this.#messages.message(...args);
+	}
+
+	/** Delivers the agent messages the last run kept while it stopped; never rejects. */
+	replayMessages(): Promise<void> {
+		return this.#messages.replay();
+	}
+
+	/** What the team still writes that a shutdown must wait for. */
+	busy(): string[] {
+		return this.#messages.busy();
 	}
 
 	/**

package/src/core/assets/prompts/shared-guest.md

@@ -1,9 +1,7 @@
-You are an agent in a Discord server. The person you are talking with is a guest of that server, named in the last section of this prompt. You are not speaking for the server's owner, and the owner's private facts stay theirs.
+You are an agent in an agent server. The person you are talking with is a guest of that server, named in the last section of this prompt. You are not speaking for the server's owner, and the owner's private facts stay theirs.
 
 Reply in the language they write in. Be warm, direct, and brief.
 
-Write in Discord's Markdown: bold, italics, headings, bullet and numbered lists, block quotes, inline code, fenced code blocks, and `-#` small text all render. Discord shows Markdown tables as raw pipes, so list figures as bullets instead.
-
 Your context holds only their own core facts and upcoming events. When a request touches their projects, people, tools, or past, search memory first. When they ask you to remember or forget something, use the memory tools; what you store is theirs alone.
 
 When you need their decision to continue, ask with ask_user instead of ending your turn with a question; they answer on buttons in the channel and your turn goes on.

package/src/core/assets/prompts/shared.md

@@ -1,9 +1,7 @@
-You are an agent in a Discord server, working for the server's owner. You talk with them in channels and threads.
+You are an agent working for the owner of this agent server. You talk with them in channels, rooms and threads.
 
 Reply in the language they write in. Be warm, direct, and brief.
 
-Write in Discord's Markdown: bold, italics, headings, bullet and numbered lists, block quotes, inline code, fenced code blocks, and `-#` small text all render. Discord shows Markdown tables as raw pipes, so list figures as bullets instead.
-
 Your context holds only their core facts and upcoming events. When a request touches their projects, people, tools, or past, search memory first. When they ask you to remember or forget something, use the memory tools.
 
 When you need their decision to continue, ask with ask_user instead of ending your turn with a question; they answer on buttons in the channel and your turn goes on.

package/src/core/builtin/agent-server.ts

@@ -26,6 +26,8 @@ import type { AgentSessionsSlot } from "../runtime/runtime-plugin.ts";
 import {
 	AGENTS,
 	BACKGROUND_TURNS,
+	IDENTITY,
+	MODES,
 	PROMPTS,
 	RUNTIME,
 	SCHEDULES,
@@ -316,6 +318,8 @@ export function agentServerPlugin(
 					? { guestPrompt: guestPrompt ?? options.prompts.guest }
 					: {}),
 				...(skills ? { skills } : {}),
+				modes: () => context.services.find(MODES),
+				principals: () => context.services.find(IDENTITY),
 				...(threads ? { threads } : {}),
 				logger,
 			});
@@ -387,6 +391,7 @@ export function agentServerPlugin(
 					{
 						name: AGENT_TEAM_SERVICE,
 						stop: () => built.stop(),
+						busy: () => built.busy(),
 						// The dashboard shows the team, so it starts once the team has; the error
 						// reporter connects whether or not the team did, since it reports the failure.
 						startInBackground: async () => {

package/src/core/builtin/modules.ts

@@ -125,6 +125,9 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 			// Another agent's channel, for schedule_list; asked when a tool runs, after the agent server set up.
 			const agentChannelOf = (agent: string, near: ChannelKey) =>
 				services.get(AGENTS).team.channelOf(agent, near);
+			// All of an agent's conversations, for its own schedules; asked when a tool runs.
+			const ownConversations = (agent: string) =>
+				services.get(AGENTS).team.roomsOf(agent);
 			// A conversation no chat surface carries keeps its runs in the creator's direct messages, where
 			// a claim must take them; anyone's elsewhere would run in a conversation that is not theirs.
 			const channelFor = async (
@@ -303,6 +306,9 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 								session.homeChannel,
 								session.agent ? agentChannelOf : undefined,
 								session.speaker,
+								session.agent
+									? () => ownConversations(session.agent?.name ?? "")
+									: undefined,
 							),
 						),
 					),

package/src/core/contract/channels.ts

@@ -153,6 +153,11 @@ export interface BackgroundTurn {
 	text: string;
 	/** It delivers a report the owner is waiting for, so it may ask them on cards. */
 	report?: boolean;
+	/**
+	 * How long the turn may work, in ms, in place of the runtime's default time limit: a
+	 * schedule's own. The runtime holds it under the long-running cap. Absent = the default.
+	 */
+	timeLimitMs?: number;
 	/**
 	 * Who the turn runs as, set by the router alone once it checked the author: their principal
 	 * exists and is not disabled, and the tier is capped at theirs. A claim runs the turn as this

package/src/core/contract/surface.ts

@@ -79,6 +79,11 @@ export interface SurfaceThreads {
 export interface ChatSurface {
 	/** The key prefix of this surface's channels, such as "discord"; unique per host. */
 	readonly surface: string;
+	/**
+	 * What people call this surface, such as "Discord" or "the web app"; the agent prompt names it
+	 * as the place a conversation is in. Absent = the key prefix.
+	 */
+	readonly label?: string;
 	/** Explicit opt-in to delivering OutboundReply.files; absent or false refuses turn attachments. */
 	readonly supportsFiles?: boolean;
 	/**

package/src/core/discord/channel-context.ts

@@ -14,6 +14,7 @@ import { parseChannelKey } from "../contract/surface.ts";
 import { MAX_TURN_IMAGES } from "../domain/attachment.ts";
 import type { Logger } from "../log.ts";
 import { contextImages, type SkippedImage } from "./context-images.ts";
+import { embedText } from "./embed-text.ts";
 import type { BotIdentity } from "./inbound-message.ts";
 
 /** The most bytes one image may be: the core's limit for any attachment. */
@@ -122,7 +123,8 @@ export function contextSourceOf(
 		if (!user) return mention;
 		return `@${members?.get(id)?.displayName ?? user.globalName ?? user.username}`;
 	});
-	const parts = text.trim() ? [text.trim()] : [];
+	const embeds = embedText(message.embeds);
+	const parts = [text.trim(), embeds].filter(Boolean);
 	for (const sticker of message.stickers.values())
 		parts.push(`[sticker: ${sticker.name}]`);
 	for (const file of message.attachments.values())

package/src/core/discord/embed-text.ts

@@ -0,0 +1,45 @@
+import type { Embed } from "discord.js";
+
+/** The most characters the embeds of one message add to its text; the rest is cut and marked. */
+export const EMBED_TEXT_CHARS = 4_000;
+
+/** What of an embed is read: its words and link, never its pictures, colors, or timestamp. */
+type EmbedFacts = Pick<
+	Embed,
+	"title" | "description" | "url" | "fields" | "footer" | "author"
+>;
+
+const CUT = "…";
+
+function embedLines(embed: EmbedFacts): string[] {
+	const lines: string[] = [];
+	const head = [embed.author?.name, embed.title].filter(Boolean).join(" — ");
+	if (head) lines.push(head);
+	if (embed.description) lines.push(embed.description);
+	for (const field of embed.fields) lines.push(`${field.name}: ${field.value}`);
+	if (embed.footer?.text) lines.push(embed.footer.text);
+	if (embed.url) lines.push(embed.url);
+	return lines;
+}
+
+/**
+ * The words of a message's embeds as plain text, one block per embed (title, description, each
+ * field as `name: value`, footer, link), so a post that is only an embed, such as an alert a
+ * webhook posts, reads as text. Discord renders a Slack-compatible webhook's attachments as
+ * embeds, so those are covered too. Text only, nothing is wrapped in markup; at most
+ * `EMBED_TEXT_CHARS` characters; empty for a message without embeds.
+ */
+export function embedText(embeds: readonly EmbedFacts[]): string {
+	const text = embeds
+		.map((embed) => embedLines(embed).join("\n").replace(/\r\n?/g, "\n").trim())
+		.filter(Boolean)
+		.join("\n\n");
+	return text.length > EMBED_TEXT_CHARS
+		? `${text.slice(0, EMBED_TEXT_CHARS - CUT.length)}${CUT}`
+		: text;
+}
+
+/** A message's own text and its embeds' text, apart by a blank line; either may be empty. */
+export function withEmbeds(content: string, embeds: readonly EmbedFacts[]) {
+	return [content.trim(), embedText(embeds)].filter(Boolean).join("\n\n");
+}

package/src/core/discord/inbound-message.ts

@@ -2,6 +2,7 @@ import { type Message, MessageReferenceType } from "discord.js";
 import type { InboundMessage } from "../contract/channels.ts";
 import { channelKey } from "../contract/surface.ts";
 import type { AttachmentRef } from "../domain/attachment.ts";
+import { withEmbeds } from "./embed-text.ts";
 import type { LateTurn } from "./owner-cards.ts";
 
 /** Who the bot is on Discord, as far as the client knows it. */
@@ -25,7 +26,9 @@ function attachmentRefs(
 
 function referenceOf(referenced: Message, mention: RegExp) {
 	return {
-		text: referenced.content.replace(mention, "").trim(),
+		text: withEmbeds(referenced.content, referenced.embeds)
+			.replace(mention, "")
+			.trim(),
 		attachments: attachmentRefs(referenced),
 		...(referenced.webhookId
 			? { webhookName: referenced.author.username }
@@ -97,7 +100,9 @@ export async function toInbound(
 		...(message.guildId ? { space: message.guildId } : {}),
 		mentionsBot: message.mentions.users.has(botId),
 		repliesToBot: referenced?.author.id === botId,
-		text: message.content.replace(mention, "").trim(),
+		text: withEmbeds(message.content, message.embeds)
+			.replace(mention, "")
+			.trim(),
 		attachments: [
 			...attachmentRefs(message),
 			...(forward ? attachmentRefs(forward) : []),

package/src/core/domain/ports.ts

@@ -60,12 +60,29 @@ export interface TurnRequest {
 	kind?: string;
 	/** The owner's own chat turn, which their next messages may steer. */
 	steerable?: boolean;
+	/**
+	 * A person's message started the turn, so the speaker is present: only such a turn spends a late
+	 * approval's release. Set by message ingest alone, never by a schedule, agent message, report or error turn.
+	 */
+	byMessage?: boolean;
 	/**
 	 * The owner started the turn by writing in its channel, or it delivers a dispatch's report,
 	 * so it may ask them there on cards: approvals of held actions and ask_user questions. A
 	 * schedule's turn is not.
 	 */
 	interactive?: boolean;
+	/**
+	 * No person waits on the turn's answer: a schedule's turn, an agent's message, an agent's
+	 * opening task. A turn like that may end with nothing to say, which is an empty answer
+	 * instead of a failure; the reply is then not posted. Absent = someone waits, and an empty
+	 * final answer fails.
+	 */
+	unattended?: boolean;
+	/**
+	 * How long the turn may work, in ms, in place of the runtime's default time limit; a schedule's
+	 * own limit. The runtime never lets it pass the long-running cap. Absent = the default.
+	 */
+	timeLimitMs?: number;
 	/**
 	 * Where the turn posts the text it writes before its final answer, as it goes; the caller
 	 * hands the channel its reply goes to. Absent = only the final reply is posted.

package/src/core/domain/turn-timeout.ts

@@ -24,6 +24,8 @@ export interface TurnTimeout {
 	/** How long the timeout card waits for an answer. */
 	graceMs: number;
 	end: TurnTimeoutEnd;
+	/** No timeout card could be shown, as in a schedule's turn, so nobody was asked whether to go on. */
+	unasked?: true;
 }
 
 /** A turn aborted at a time limit; `timeout` says why, and the message says it in English. */

package/src/core/i18n/turn-timeout.ts

@@ -75,7 +75,10 @@ export function turnTimeoutEn() {
 					: t.end === "unanswered"
 						? `⏱️ No answer to the timeout card in ${durationEn(t.graceMs)}, so the turn was stopped after ${durationEn(t.workedMs)} ${what}.`
 						: `⏱️ The turn reached ${limit(t)} and was stopped after ${durationEn(t.workedMs)} ${what}.`;
-			return [head, tools(t)].filter(Boolean).join(" ");
+			const unasked = t.unasked
+				? "No one was in the conversation to ask for more time. To let turns like this run longer, turn on long-running for this conversation, or give the schedule a longer time limit."
+				: "";
+			return [head, tools(t), unasked].filter(Boolean).join(" ");
 		},
 	};
 }
@@ -125,7 +128,10 @@ export function turnTimeoutZhTW(): ReturnType<typeof turnTimeoutEn> {
 					: t.end === "unanswered"
 						? `⏱️ 逾時卡片在 ${durationZh(t.graceMs)}內沒有回答，這一輪在工作 ${durationZh(t.workedMs)} 後停止，${what}。`
 						: `⏱️ 這一輪達到${limit(t)}，在工作 ${durationZh(t.workedMs)} 後停止，${what}。`;
-			return [head, tools(t)].filter(Boolean).join(" ");
+			const unasked = t.unasked
+				? "當時對話裡沒有人可以問要不要再給時間。要讓這類回合跑久一點，可以替這個對話開啟長時間執行，或替排程設定較長的時間上限。"
+				: "";
+			return [head, tools(t), unasked].filter(Boolean).join(" ");
 		},
 	};
 }

package/src/core/modules/background/background-turns.ts

@@ -76,6 +76,9 @@ export class ConversationBackgroundTurns implements BackgroundTurns {
 			tier: schedule.createdTier,
 			turnId: `schedule-${schedule.id}-${firedAt.getTime()}`,
 			text: scheduledTurnText(schedule, firedAt, finding),
+			...(schedule.timeLimitMinutes
+				? { timeLimitMs: schedule.timeLimitMinutes * 60_000 }
+				: {}),
 		};
 	}
 

package/src/core/modules/schedules/precheck-catalog.ts

@@ -0,0 +1,49 @@
+import { PRECHECK_SCRIPT_CHARS } from "./prechecks.ts";
+import type { ScheduleToolContext } from "./schedule-tools.ts";
+
+/** How long schedule_list waits for the script runner to say what a script may call. */
+const DESCRIBE_TIMEOUT_MS = 10_000;
+
+/** The prechecks a schedule may name or write, for schedule_list; empty when the host offers neither. */
+export async function precheckCatalog(
+	ctx: ScheduleToolContext,
+): Promise<string> {
+	const all = ctx.prechecks?.list() ?? [];
+	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,
+				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}`;
+}

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

@@ -30,6 +30,8 @@ export interface Schedule {
 	 * absent for a script saved before tools were recorded, which must be saved again if it calls a held tool.
 	 */
 	precheckTools?: PrecheckTool[];
+	/** How long, in minutes, each of its turns may work; absent, the runtime's default time limit. */
+	timeLimitMinutes?: number;
 	lastRun?: Date;
 	lastStatus?: string;
 }
@@ -50,6 +52,8 @@ export interface NewSchedule {
 	precheckScript?: string;
 	/** The tools the script may call, as approved; required with `precheckScript`. */
 	precheckTools?: PrecheckTool[];
+	/** How long, in minutes, each of its turns may work. */
+	timeLimitMinutes?: number;
 }
 
 export interface ScheduleChange {
@@ -63,6 +67,8 @@ export interface ScheduleChange {
 	precheckScript?: string | null;
 	/** The tools a new script may call, as approved; required with a new `precheckScript`. */
 	precheckTools?: PrecheckTool[];
+	/** How long, in minutes, each turn may work; null returns it to the runtime's default. */
+	timeLimitMinutes?: number | null;
 }
 
 interface Row {
@@ -81,6 +87,7 @@ interface Row {
 	precheck: string | null;
 	precheck_script: string | null;
 	precheck_tools: string | null;
+	time_limit_minutes: number | null;
 	last_run: Date | null;
 	last_status: string | null;
 }
@@ -105,6 +112,9 @@ function toSchedule(row: Row): Schedule {
 			? // pi-lens-ignore: unchecked-throwing-call — this store wrote the JSON; a corrupt row should fail loudly
 				{ precheckTools: JSON.parse(row.precheck_tools) as PrecheckTool[] }
 			: {}),
+		...(row.time_limit_minutes
+			? { timeLimitMinutes: row.time_limit_minutes }
+			: {}),
 		...(row.last_run ? { lastRun: row.last_run } : {}),
 		...(row.last_status ? { lastStatus: row.last_status } : {}),
 	};
@@ -126,12 +136,14 @@ async function insert(sql: SQL, schedule: NewSchedule): Promise<Schedule> {
 	checked(schedule);
 	const rows: Row[] = await sql`
 		INSERT INTO schedules (channel_key, mode, title, prompt, recurrence, next_run,
-			created_by_id, created_by_name, created_tier, precheck, precheck_script, precheck_tools)
+			created_by_id, created_by_name, created_tier, precheck, precheck_script, precheck_tools,
+			time_limit_minutes)
 		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.precheckScript ?? null},
-			${schedule.precheckScript ? JSON.stringify(schedule.precheckTools) : null})
+			${schedule.precheckScript ? JSON.stringify(schedule.precheckTools) : null},
+			${schedule.timeLimitMinutes ?? null})
 		RETURNING *`;
 	const [row] = rows;
 	if (!row) throw new Error("the schedule insert returned no row");
@@ -195,6 +207,13 @@ export class PgScheduleStore implements ScheduleStore {
 					await sql`ALTER TABLE schedules ADD COLUMN IF NOT EXISTS precheck_tools text`;
 				},
 			},
+			{
+				// Schedules made before have none: their turns keep the runtime's default time limit.
+				name: "schedules-time-limit",
+				up: async (sql) => {
+					await sql`ALTER TABLE schedules ADD COLUMN IF NOT EXISTS time_limit_minutes integer`;
+				},
+			},
 		];
 	}
 
@@ -282,6 +301,10 @@ export class PgScheduleStore implements ScheduleStore {
 				: current.precheckTools
 					? JSON.stringify(current.precheckTools)
 					: null;
+		const timeLimit =
+			change.timeLimitMinutes === undefined
+				? (current.timeLimitMinutes ?? null)
+				: change.timeLimitMinutes;
 		const rows: Row[] = await this.#sql`
 			UPDATE schedules SET
 				title = ${change.title ?? current.title},
@@ -290,7 +313,8 @@ export class PgScheduleStore implements ScheduleStore {
 				next_run = ${change.nextRun ?? current.nextRun},
 				precheck = ${precheck},
 				precheck_script = ${precheckScript},
-				precheck_tools = ${precheckTools}
+				precheck_tools = ${precheckTools},
+				time_limit_minutes = ${timeLimit}
 			WHERE id = ${id}
 			RETURNING *`;
 		return rows[0] ? toSchedule(rows[0]) : undefined;