Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import { tool, zodSchema } from 'ai';
import { z } from 'zod';
import { randomUUID } from 'node:crypto';
import { logger } from '../../utils/logger.js';
export interface BotScheduler {
addDelayedTask(manifest: {
id: string;
description: string;
prompt: string;
delaySeconds?: number;
executeAt?: string;
botId?: string;
createdAt: string;
}): void;
addPersistedTask(manifest: {
id: string;
cron: string;
description: string;
prompt: string;
botId?: string;
createdAt: string;
}): void;
persistSchedules(): void;
/** All live manifests, used for the per-bot self-schedule cap. */
getManifests(): Array<{ id: string; botId?: string; lastRun?: { status: string } }>;
}
const SELF_PREFIX = 'self-';
const ROUTINE_PREFIX = 'routine-';
const MAX_DELAY_MINUTES = 60 * 24 * 30; // 30 days
const MAX_PENDING_SELF_SCHEDULES = 10;
/** Bot-created routines: never more often than this, never more than this many. ADR-020. */
const MIN_ROUTINE_GAP_MINUTES = 30;
const MAX_SELF_ROUTINES = 3;
const MIN_ONESHOT_DELAY_MINUTES = 10;
/** Smallest gap (minutes) a 5-field cron's minute field can produce; Infinity when it cannot tell. */
export function cronMinGapMinutes(cron: string): number {
const minute = cron.trim().split(/\s+/)[0] ?? '';
const hour = cron.trim().split(/\s+/)[1] ?? '';
if (minute === '*') return 1;
const step = /^\*\/(\d+)$/.exec(minute);
if (step) return Math.max(1, Number(step[1]));
const values = minute.split(',').map(v => Number(v)).filter(v => Number.isInteger(v)).sort((a, b) => a - b);
if (values.length === 0) return Infinity;
if (values.length === 1) return hour === '*' || /^\*\//.test(hour) ? 60 : Infinity;
let gap = Infinity;
for (let i = 1; i < values.length; i++) gap = Math.min(gap, values[i] - values[i - 1]);
gap = Math.min(gap, 60 - values[values.length - 1] + values[0]);
return gap;
}
/**
* bot_schedule — a bot schedules its OWN future run (durable, persisted with
* the fleet's schedules): one-shot delayed runs ("post again in an hour") or
* self-created recurring routines. Guardrails keep runaway loops bounded:
* prompts are capped, delays are capped, and a bot can have at most
* MAX_PENDING_SELF_SCHEDULES pending one-shots.
*/
export function createBotScheduleTool(scheduler: BotScheduler, botId: string) {
return tool({
description:
'Schedule work for yourself in the future. Use when a task needs a follow-up later (e.g. "post the follow-up in one hour") ' +
'or a recurring routine. One-shot: delayMinutes (or executeAt ISO date). Recurring: cron (5 fields). ' +
'The scheduled run starts fresh with your persona and tools; results are delivered like any other run.',
inputSchema: zodSchema(z.object({
prompt: z.string().min(1).max(4000).describe('What you should do on the future run — self-contained, include all needed context'),
delayMinutes: z.number().min(1).max(MAX_DELAY_MINUTES).optional().describe('One-shot: run again after this many minutes (1..43200)'),
executeAt: z.string().optional().describe('One-shot alternative: ISO timestamp to run at'),
cron: z.string().optional().describe('Recurring: 5-field cron expression, e.g. "0 9 * * 1"'),
name: z.string().max(40).optional().describe('Label for recurring routines (required with cron)'),
})),
execute: async ({ prompt, delayMinutes, executeAt, cron, name }: {
prompt: string; delayMinutes?: number; executeAt?: string; cron?: string; name?: string;
}) => {
const hasDelay = delayMinutes !== undefined || executeAt !== undefined;
if (hasDelay === Boolean(cron)) {
return 'Error: choose exactly one — delayMinutes/executeAt for a one-shot, or cron for a recurring routine.';
}
if (cron) {
if (!name) return 'Error: cron schedules need a name (used to update/replace the routine later).';
if (cron.trim().split(/\s+/).length !== 5) {
return `Error: "${cron}" is not a 5-field cron expression.`;
}
if (cronMinGapMinutes(cron) < MIN_ROUTINE_GAP_MINUTES) {
return `Error: routines run at most every ${MIN_ROUTINE_GAP_MINUTES} minutes — "${cron}" fires more often. A wake that finds nothing to do still costs a full turn; schedule follow-ups with delayMinutes instead.`;
}
const routines = scheduler.getManifests().filter(m => m.botId === botId && m.id.includes(`:${ROUTINE_PREFIX}`));
const replacing = routines.some(m => m.id === `bot:${botId}:${ROUTINE_PREFIX}${name.toLowerCase().replace(/[^a-z0-9-]+/g, '-')}`);
if (!replacing && routines.length >= MAX_SELF_ROUTINES) {
return `Error: you already have ${MAX_SELF_ROUTINES} routines (${routines.map(m => m.id.split(':' + ROUTINE_PREFIX)[1]).join(', ')}). Re-use one of those names to replace it, or ask the owner to add more in bot.yaml.`;
}
const id = `bot:${botId}:${ROUTINE_PREFIX}${name.toLowerCase().replace(/[^a-z0-9-]+/g, '-')}`;
scheduler.addPersistedTask({
id,
cron,
description: name,
prompt,
botId,
createdAt: new Date().toISOString(),
});
scheduler.persistSchedules();
logger.info({ botId, id, cron }, 'Bot self-scheduled a recurring routine');
return `Scheduled: routine "${name}" (${cron}) — fires through the cron lane; results land in your chat like any other run. Manage via /bots.`;
}
// One-shot with a pending cap — this is the runaway-loop guard.
const pending = scheduler.getManifests().filter(m => m.botId === botId && m.id.includes(`:${SELF_PREFIX}`) && (!m.lastRun || m.lastRun.status === 'running')).length;
if (pending >= MAX_PENDING_SELF_SCHEDULES) {
return `Error: you already have ${MAX_PENDING_SELF_SCHEDULES} pending self-scheduled runs — complete or let them fire before adding more.`;
}
let delaySeconds: number;
if (executeAt) {
const at = new Date(executeAt);
if (Number.isNaN(at.getTime())) return `Error: "${executeAt}" is not a valid ISO timestamp.`;
delaySeconds = Math.max(1, Math.ceil((at.getTime() - Date.now()) / 1000));
if (delaySeconds > MAX_DELAY_MINUTES * 60) {
return `Error: scheduled time is beyond the ${MAX_DELAY_MINUTES / 60 / 24}-day horizon.`;
}
} else {
if ((delayMinutes as number) > MAX_DELAY_MINUTES) {
return `Error: delayMinutes exceeds the ${MAX_DELAY_MINUTES / 60 / 24}-day horizon.`;
}
if ((delayMinutes as number) < MIN_ONESHOT_DELAY_MINUTES) {
return `Error: a follow-up run must be at least ${MIN_ONESHOT_DELAY_MINUTES} minutes out — if the work is not done yet, keep working in this turn.`;
}
delaySeconds = Math.round((delayMinutes as number) * 60);
}
const id = `bot:${botId}:${SELF_PREFIX}${randomUUID().slice(0, 8)}`;
const executeAtIso = new Date(Date.now() + delaySeconds * 1000).toISOString();
scheduler.addDelayedTask({
id,
description: 'bot self-schedule',
prompt,
delaySeconds,
executeAt: executeAtIso,
botId,
createdAt: new Date().toISOString(),
});
scheduler.persistSchedules();
logger.info({ botId, id, executeAtIso }, 'Bot self-scheduled a one-shot run');
return `Scheduled: this run will fire in ${Math.round(delaySeconds / 60)} min (at ${executeAtIso}). It survives restarts; prompt: "${prompt.slice(0, 80)}"`;
},
});
}