discoclaw 0.1.0

package/dist/discord/actions-crons.js

@@ -0,0 +1,586 @@
+import { Cron } from 'croner';
+import { CADENCE_TAGS, generateCronId } from '../cron/run-stats.js';
+import { detectCadence } from '../cron/cadence.js';
+import { autoTagCron, classifyCronModel } from '../cron/auto-tag.js';
+import { buildCronThreadName, ensureStatusMessage, resolveForumChannel } from '../cron/discord-sync.js';
+import { reloadCronTagMapInPlace } from '../cron/tag-map.js';
+import { getDefaultTimezone } from '../cron/default-timezone.js';
+const CRON_TYPE_MAP = {
+    cronCreate: true,
+    cronUpdate: true,
+    cronList: true,
+    cronShow: true,
+    cronPause: true,
+    cronResume: true,
+    cronDelete: true,
+    cronTrigger: true,
+    cronSync: true,
+    cronTagMapReload: true,
+};
+export const CRON_ACTION_TYPES = new Set(Object.keys(CRON_TYPE_MAP));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildStarterContent(schedule, timezone, channel, prompt) {
+    return `**Schedule:** \`${schedule}\` (${timezone})\n**Channel:** #${channel}\n\n${prompt}`;
+}
+function validateCronDefinition(def) {
+    const timezone = String(def.timezone ?? '').trim();
+    if (!timezone) {
+        return 'timezone is required';
+    }
+    try {
+        Intl.DateTimeFormat(undefined, { timeZone: timezone });
+    }
+    catch {
+        return `invalid timezone "${def.timezone}"`;
+    }
+    try {
+        new Cron(def.schedule, { timezone }).stop();
+        return null;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return msg || 'invalid schedule';
+    }
+}
+function requestRunningJobCancel(cronCtx, threadId, cronId) {
+    const canceled = cronCtx.executorCtx?.runControl?.requestCancel(threadId) ?? false;
+    if (canceled) {
+        cronCtx.log?.info({ cronId, threadId }, 'cron:action requested cancel for in-flight run');
+    }
+    return canceled;
+}
+// ---------------------------------------------------------------------------
+// Executor
+// ---------------------------------------------------------------------------
+export async function executeCronAction(action, ctx, cronCtx) {
+    switch (action.type) {
+        case 'cronCreate': {
+            if (!action.name || !action.schedule || !action.channel || !action.prompt) {
+                return { ok: false, error: 'cronCreate requires name, schedule, channel, and prompt' };
+            }
+            const cronId = generateCronId();
+            const timezone = action.timezone ?? getDefaultTimezone();
+            const def = { triggerType: 'schedule', schedule: action.schedule, timezone, channel: action.channel, prompt: action.prompt };
+            const validationError = validateCronDefinition(def);
+            if (validationError) {
+                return { ok: false, error: `Invalid cron definition: ${validationError}` };
+            }
+            const cadence = detectCadence(def.schedule);
+            // Create forum thread.
+            const forum = await resolveForumChannel(cronCtx.client, cronCtx.forumId);
+            if (!forum) {
+                return { ok: false, error: 'Cron forum channel not found' };
+            }
+            // Reload shared cache from disk (best-effort; failure keeps cached)
+            await reloadCronTagMapInPlace(cronCtx.tagMapPath, cronCtx.tagMap).catch((err) => {
+                cronCtx.log?.warn({ err, tagMapPath: cronCtx.tagMapPath }, 'cron:action tag-map reload failed; using cached');
+            });
+            // Snapshot for deterministic use within this action
+            const tagMap = { ...cronCtx.tagMap };
+            // Auto-tag if enabled.
+            const cadenceSet = new Set(CADENCE_TAGS);
+            const purposeTagNames = Object.keys(tagMap).filter((k) => !cadenceSet.has(k));
+            let purposeTags = [];
+            let model = null;
+            if (action.tags) {
+                purposeTags = action.tags.split(',').map((t) => t.trim()).filter(Boolean);
+            }
+            if (cronCtx.autoTag && purposeTagNames.length > 0 && purposeTags.length === 0) {
+                try {
+                    purposeTags = await autoTagCron(cronCtx.runtime, action.name, action.prompt, purposeTagNames, { model: cronCtx.autoTagModel, cwd: cronCtx.cwd });
+                }
+                catch (err) {
+                    cronCtx.log?.warn({ err, cronId }, 'cron:action:create auto-tag failed');
+                }
+            }
+            // Classify model.
+            if (action.model) {
+                model = action.model;
+            }
+            else {
+                try {
+                    model = await classifyCronModel(cronCtx.runtime, action.name, action.prompt, cadence, { model: cronCtx.autoTagModel, cwd: cronCtx.cwd });
+                }
+                catch {
+                    model = 'fast';
+                }
+            }
+            // Resolve tag IDs for forum.
+            const allTagNames = [...purposeTags, cadence];
+            const appliedTagIds = allTagNames.map((t) => tagMap[t]).filter(Boolean);
+            const uniqueTagIds = [...new Set(appliedTagIds)].slice(0, 5);
+            const threadName = buildCronThreadName(action.name, cadence);
+            const starterContent = buildStarterContent(action.schedule, timezone, action.channel, action.prompt);
+            let thread;
+            try {
+                thread = await forum.threads.create({
+                    name: threadName,
+                    message: {
+                        content: starterContent.slice(0, 2000),
+                        allowedMentions: { parse: [] },
+                    },
+                    appliedTags: uniqueTagIds,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { ok: false, error: `Failed to create forum thread: ${msg}` };
+            }
+            // Mark thread as pending so the threadCreate listener skips it.
+            cronCtx.pendingThreadIds.add(thread.id);
+            // Register with scheduler, then clear the pending marker.
+            try {
+                cronCtx.scheduler.register(thread.id, thread.id, ctx.guild.id, action.name, def, cronId);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { ok: false, error: `Invalid cron definition: ${msg}` };
+            }
+            finally {
+                cronCtx.pendingThreadIds.delete(thread.id);
+            }
+            // Save stats. On create, set the classified model but don't set modelOverride —
+            // override is only for explicit user changes via cronUpdate.
+            const record = await cronCtx.statsStore.upsertRecord(cronId, thread.id, {
+                cadence,
+                purposeTags,
+                model,
+            });
+            // Create status message.
+            try {
+                await ensureStatusMessage(cronCtx.client, thread.id, cronId, record, cronCtx.statsStore, { log: cronCtx.log });
+            }
+            catch { }
+            cronCtx.forumCountSync?.requestUpdate();
+            return { ok: true, summary: `Cron "${action.name}" created (${cronId}), schedule: ${action.schedule}, model: ${model}` };
+        }
+        case 'cronUpdate': {
+            if (!action.cronId) {
+                return { ok: false, error: 'cronUpdate requires cronId' };
+            }
+            const record = cronCtx.statsStore.getRecord(action.cronId);
+            if (!record) {
+                return { ok: false, error: `Cron "${action.cronId}" not found` };
+            }
+            const job = cronCtx.scheduler.getJob(record.threadId);
+            if (!job) {
+                return { ok: false, error: `Cron "${action.cronId}" not registered in scheduler` };
+            }
+            const updates = {};
+            const changes = [];
+            // Model override.
+            if (action.model) {
+                updates.modelOverride = action.model;
+                changes.push(`model → ${action.model}`);
+            }
+            // Tags override.
+            if (action.tags) {
+                updates.purposeTags = action.tags.split(',').map((t) => t.trim()).filter(Boolean);
+                changes.push(`tags → ${updates.purposeTags.join(', ')}`);
+            }
+            // Definition changes (schedule, timezone, channel, prompt).
+            const newSchedule = action.schedule ?? job.def.schedule ?? '';
+            const newTimezone = action.timezone ?? job.def.timezone;
+            const newChannel = action.channel ?? job.def.channel;
+            const newPrompt = action.prompt ?? job.def.prompt;
+            const newDef = { triggerType: job.def.triggerType, schedule: newSchedule, timezone: newTimezone, channel: newChannel, prompt: newPrompt };
+            const defChanged = action.schedule !== undefined || action.timezone !== undefined || action.channel !== undefined || action.prompt !== undefined;
+            if (defChanged) {
+                const validationError = validateCronDefinition(newDef);
+                if (validationError) {
+                    return { ok: false, error: `Invalid cron definition: ${validationError}` };
+                }
+                // Update cadence if schedule changed.
+                if (action.schedule) {
+                    updates.cadence = detectCadence(action.schedule);
+                    changes.push(`schedule → ${action.schedule}`);
+                }
+                if (action.timezone !== undefined)
+                    changes.push(`timezone → ${action.timezone}`);
+                if (action.channel !== undefined)
+                    changes.push(`channel → ${action.channel}`);
+                if (action.prompt !== undefined)
+                    changes.push(`prompt updated`);
+                // Try to edit the thread's starter message (works for bot-created threads).
+                const thread = cronCtx.client.channels.cache.get(record.threadId);
+                if (thread && thread.isThread()) {
+                    try {
+                        const starter = await thread.fetchStarterMessage();
+                        if (starter && starter.author.id === cronCtx.client.user?.id) {
+                            const newContent = buildStarterContent(newSchedule, newTimezone, newChannel, newPrompt);
+                            await starter.edit({ content: newContent.slice(0, 2000), allowedMentions: { parse: [] } });
+                        }
+                        else {
+                            // Can't edit user's message — post update note.
+                            const note = `**Cron Updated**\n**Schedule:** \`${newSchedule}\` (${newTimezone})\n**Channel:** #${newChannel}\n\nPlease update the starter message to reflect these changes.`;
+                            await thread.send({ content: note, allowedMentions: { parse: [] } });
+                        }
+                    }
+                    catch (err) {
+                        cronCtx.log?.warn({ err, cronId: action.cronId }, 'cron:action:update edit failed');
+                    }
+                }
+                // Reload scheduler.
+                try {
+                    cronCtx.scheduler.register(record.threadId, record.threadId, job.guildId, job.name, newDef, action.cronId);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { ok: false, error: `Invalid cron definition: ${msg}` };
+                }
+            }
+            await cronCtx.statsStore.upsertRecord(action.cronId, record.threadId, updates);
+            // Update status message.
+            try {
+                const updatedRecord = cronCtx.statsStore.getRecord(action.cronId);
+                if (updatedRecord) {
+                    await ensureStatusMessage(cronCtx.client, record.threadId, action.cronId, updatedRecord, cronCtx.statsStore, { log: cronCtx.log });
+                }
+            }
+            catch { }
+            // Update thread tags if needed.
+            if (action.tags !== undefined || action.schedule !== undefined) {
+                try {
+                    // Reload shared cache from disk (best-effort; failure keeps cached)
+                    await reloadCronTagMapInPlace(cronCtx.tagMapPath, cronCtx.tagMap).catch((err) => {
+                        cronCtx.log?.warn({ err, tagMapPath: cronCtx.tagMapPath }, 'cron:action tag-map reload failed; using cached');
+                    });
+                    // Snapshot for deterministic use within this action
+                    const tagMap = { ...cronCtx.tagMap };
+                    const updatedRecord = cronCtx.statsStore.getRecord(action.cronId);
+                    if (updatedRecord) {
+                        const allTags = [...updatedRecord.purposeTags];
+                        if (updatedRecord.cadence)
+                            allTags.push(updatedRecord.cadence);
+                        const tagIds = allTags.map((t) => tagMap[t]).filter(Boolean);
+                        const uniqueTagIds = [...new Set(tagIds)].slice(0, 5);
+                        if (uniqueTagIds.length > 0) {
+                            const thread = cronCtx.client.channels.cache.get(record.threadId);
+                            if (thread && thread.isThread()) {
+                                await thread.edit({ appliedTags: uniqueTagIds });
+                            }
+                        }
+                    }
+                }
+                catch { }
+            }
+            return { ok: true, summary: `Cron ${action.cronId} updated: ${changes.join(', ') || 'no changes'}` };
+        }
+        case 'cronList': {
+            const jobs = cronCtx.scheduler.listJobs();
+            if (jobs.length === 0) {
+                return { ok: true, summary: 'No cron jobs registered.' };
+            }
+            const lines = jobs.map((j) => {
+                const fullJob = cronCtx.scheduler.getJob(j.id);
+                const record = fullJob?.cronId ? cronCtx.statsStore.getRecord(fullJob.cronId) : undefined;
+                const status = record?.disabled ? 'paused' : (record?.lastRunStatus ?? 'pending');
+                const displayStatus = fullJob?.running ? `${status} \uD83D\uDD04` : status;
+                const model = record?.modelOverride ?? record?.model ?? '?';
+                const runs = record?.runCount ?? 0;
+                const tags = record?.purposeTags?.join(', ') || '';
+                const nextRun = j.nextRun ? `<t:${Math.floor(j.nextRun.getTime() / 1000)}:R>` : 'N/A';
+                const cronId = fullJob?.cronId ?? '?';
+                return `\`${cronId}\` **${j.name}** | \`${j.schedule}\` | ${displayStatus} | ${model} | ${runs} runs | next: ${nextRun}${tags ? ` | ${tags}` : ''}`;
+            });
+            return { ok: true, summary: lines.join('\n') };
+        }
+        case 'cronShow': {
+            if (!action.cronId) {
+                return { ok: false, error: 'cronShow requires cronId' };
+            }
+            const record = cronCtx.statsStore.getRecord(action.cronId);
+            if (!record) {
+                return { ok: false, error: `Cron "${action.cronId}" not found` };
+            }
+            const job = cronCtx.scheduler.getJob(record.threadId);
+            const lines = [];
+            lines.push(`**Cron: ${job?.name ?? 'Unknown'}** (\`${action.cronId}\`)`);
+            lines.push(`Thread: ${record.threadId}`);
+            if (job) {
+                lines.push(`Schedule: \`${job.def.schedule}\` (${job.def.timezone})`);
+                const nextRun = job.cron?.nextRun() ?? null;
+                lines.push(`Next run: ${nextRun ? `<t:${Math.floor(nextRun.getTime() / 1000)}:F>` : 'N/A'}`);
+            }
+            lines.push(`Status: ${record.disabled ? 'paused' : 'active'}`);
+            if (job?.running) {
+                lines.push(`Runtime: \uD83D\uDD04 running`);
+            }
+            lines.push(`Model: ${record.modelOverride ?? record.model ?? 'N/A'}${record.modelOverride ? ' (override)' : ''}`);
+            lines.push(`Cadence: ${record.cadence ?? 'N/A'}`);
+            lines.push(`Runs: ${record.runCount} | Last: ${record.lastRunStatus ?? 'never'}`);
+            if (record.lastRunAt)
+                lines.push(`Last run: <t:${Math.floor(new Date(record.lastRunAt).getTime() / 1000)}:R>`);
+            if (record.purposeTags.length > 0)
+                lines.push(`Tags: ${record.purposeTags.join(', ')}`);
+            if (record.lastErrorMessage)
+                lines.push(`Last error: ${record.lastErrorMessage}`);
+            return { ok: true, summary: lines.join('\n') };
+        }
+        case 'cronPause': {
+            if (!action.cronId) {
+                return { ok: false, error: 'cronPause requires cronId' };
+            }
+            const record = cronCtx.statsStore.getRecord(action.cronId);
+            if (!record) {
+                return { ok: false, error: `Cron "${action.cronId}" not found` };
+            }
+            const disabled = cronCtx.scheduler.disable(record.threadId);
+            if (!disabled) {
+                return { ok: false, error: `Cron "${action.cronId}" not registered in scheduler` };
+            }
+            const canceled = requestRunningJobCancel(cronCtx, record.threadId, action.cronId);
+            await cronCtx.statsStore.upsertRecord(action.cronId, record.threadId, { disabled: true });
+            // Post notification.
+            try {
+                const thread = cronCtx.client.channels.cache.get(record.threadId);
+                if (thread && thread.isThread()) {
+                    await thread.send({ content: '\u23F8\uFE0F **Cron paused**', allowedMentions: { parse: [] } });
+                }
+            }
+            catch { }
+            return { ok: true, summary: canceled ? `Cron ${action.cronId} paused (active run cancel requested)` : `Cron ${action.cronId} paused` };
+        }
+        case 'cronResume': {
+            if (!action.cronId) {
+                return { ok: false, error: 'cronResume requires cronId' };
+            }
+            const record = cronCtx.statsStore.getRecord(action.cronId);
+            if (!record) {
+                return { ok: false, error: `Cron "${action.cronId}" not found` };
+            }
+            const enabled = cronCtx.scheduler.enable(record.threadId);
+            if (!enabled) {
+                return { ok: false, error: `Cron "${action.cronId}" not registered in scheduler` };
+            }
+            await cronCtx.statsStore.upsertRecord(action.cronId, record.threadId, { disabled: false });
+            // Post notification.
+            try {
+                const thread = cronCtx.client.channels.cache.get(record.threadId);
+                if (thread && thread.isThread()) {
+                    await thread.send({ content: '\u25B6\uFE0F **Cron resumed**', allowedMentions: { parse: [] } });
+                }
+            }
+            catch { }
+            return { ok: true, summary: `Cron ${action.cronId} resumed` };
+        }
+        case 'cronDelete': {
+            if (!action.cronId) {
+                return { ok: false, error: 'cronDelete requires cronId' };
+            }
+            const record = cronCtx.statsStore.getRecord(action.cronId);
+            if (!record) {
+                return { ok: false, error: `Cron "${action.cronId}" not found` };
+            }
+            const canceled = requestRunningJobCancel(cronCtx, record.threadId, action.cronId);
+            cronCtx.scheduler.unregister(record.threadId);
+            await cronCtx.statsStore.removeRecord(action.cronId);
+            cronCtx.forumCountSync?.requestUpdate();
+            // Archive the thread.
+            const thread = cronCtx.client.channels.cache.get(record.threadId);
+            if (thread && thread.isThread()) {
+                try {
+                    await thread.send({ content: '\uD83D\uDDD1\uFE0F **Cron deleted**', allowedMentions: { parse: [] } });
+                }
+                catch { }
+                try {
+                    await thread.setArchived(true);
+                }
+                catch (err) {
+                    cronCtx.log?.warn({ err, cronId: action.cronId, threadId: record.threadId }, 'cron:action:delete archive failed');
+                    return {
+                        ok: true,
+                        summary: canceled
+                            ? `Cron ${action.cronId} deleted (active run cancel requested) but thread could not be archived — archive it manually`
+                            : `Cron ${action.cronId} deleted but thread could not be archived — archive it manually`,
+                    };
+                }
+            }
+            return {
+                ok: true,
+                summary: canceled
+                    ? `Cron ${action.cronId} deleted and thread archived (active run cancel requested)`
+                    : `Cron ${action.cronId} deleted and thread archived`,
+            };
+        }
+        case 'cronTrigger': {
+            if (!action.cronId) {
+                return { ok: false, error: 'cronTrigger requires cronId' };
+            }
+            const record = cronCtx.statsStore.getRecord(action.cronId);
+            if (!record) {
+                return { ok: false, error: `Cron "${action.cronId}" not found` };
+            }
+            const job = cronCtx.scheduler.getJob(record.threadId);
+            if (!job) {
+                return { ok: false, error: `Cron "${action.cronId}" not found in scheduler` };
+            }
+            if (action.force) {
+                return {
+                    ok: false,
+                    error: 'cronTrigger force is disabled in Discord actions; use an admin terminal flow for break-glass overrides',
+                };
+            }
+            // Fire the executor (deferred import to avoid circular).
+            try {
+                const { executeCronJob } = await import('../cron/executor.js');
+                // Use the real executor context if available (wired in from index.ts),
+                // falling back to a minimal context with reduced capabilities.
+                const execCtx = cronCtx.executorCtx ?? {
+                    client: cronCtx.client,
+                    runtime: cronCtx.runtime,
+                    model: record.modelOverride ?? record.model ?? 'fast',
+                    cwd: cronCtx.cwd,
+                    tools: [],
+                    timeoutMs: 600_000,
+                    status: null,
+                    log: cronCtx.log,
+                    discordActionsEnabled: false,
+                    actionFlags: { channels: false, messaging: false, guild: false, moderation: false, polls: false, tasks: false, crons: false, botProfile: false, forge: false, plan: false, memory: false, config: false, defer: false },
+                    deferScheduler: cronCtx.deferScheduler,
+                    statsStore: cronCtx.statsStore,
+                };
+                void executeCronJob(job, execCtx);
+                return { ok: true, summary: `Cron ${action.cronId} triggered (running in background)` };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { ok: false, error: `Trigger failed: ${msg}` };
+            }
+        }
+        case 'cronSync': {
+            try {
+                if (cronCtx.syncCoordinator) {
+                    const result = await cronCtx.syncCoordinator.sync();
+                    if (result === null) {
+                        return { ok: true, summary: 'Cron sync already running; request coalesced' };
+                    }
+                    return {
+                        ok: true,
+                        summary: `Cron sync complete: ${result.tagsApplied} tags, ${result.namesUpdated} names, ${result.statusMessagesUpdated} status msgs, ${result.orphansDetected} orphans`,
+                    };
+                }
+                else {
+                    // Fallback (no coordinator): reload + snapshot + runCronSync + forumCountSync
+                    await reloadCronTagMapInPlace(cronCtx.tagMapPath, cronCtx.tagMap).catch((err) => {
+                        cronCtx.log?.warn({ err, tagMapPath: cronCtx.tagMapPath }, 'cron:sync tag-map reload failed; using cached');
+                    });
+                    const tagMapSnapshot = { ...cronCtx.tagMap };
+                    const { runCronSync } = await import('../cron/cron-sync.js');
+                    const result = await runCronSync({
+                        client: cronCtx.client,
+                        forumId: cronCtx.forumId,
+                        scheduler: cronCtx.scheduler,
+                        statsStore: cronCtx.statsStore,
+                        runtime: cronCtx.runtime,
+                        tagMap: tagMapSnapshot,
+                        autoTag: cronCtx.autoTag,
+                        autoTagModel: cronCtx.autoTagModel,
+                        cwd: cronCtx.cwd,
+                        log: cronCtx.log,
+                    });
+                    cronCtx.forumCountSync?.requestUpdate();
+                    return {
+                        ok: true,
+                        summary: `Cron sync complete: ${result.tagsApplied} tags, ${result.namesUpdated} names, ${result.statusMessagesUpdated} status msgs, ${result.orphansDetected} orphans`,
+                    };
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { ok: false, error: `Cron sync failed: ${msg}` };
+            }
+        }
+        case 'cronTagMapReload': {
+            const oldCount = Object.keys(cronCtx.tagMap).length;
+            try {
+                const newCount = await reloadCronTagMapInPlace(cronCtx.tagMapPath, cronCtx.tagMap);
+                const tagNames = Object.keys(cronCtx.tagMap).slice(0, 10);
+                const tagList = tagNames.join(', ') + (Object.keys(cronCtx.tagMap).length > 10 ? ', ...' : '');
+                let summary = `Tag map reloaded: ${oldCount} → ${newCount} tags [${tagList}]`;
+                if (cronCtx.syncCoordinator) {
+                    cronCtx.syncCoordinator.sync().catch((err) => {
+                        cronCtx.log?.warn({ err }, 'cron:tagMapReload post-reload sync failed');
+                    });
+                    summary += '; sync queued';
+                }
+                else {
+                    summary += '; no sync coordinator configured';
+                }
+                return { ok: true, summary };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { ok: false, error: `Tag map reload failed: ${msg}` };
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Prompt section
+// ---------------------------------------------------------------------------
+export function cronActionsPromptSection() {
+    return `### Cron Scheduled Tasks
+
+**cronCreate** — Create a new scheduled task:
+\`\`\`
+<discord-action>{"type":"cronCreate","name":"Morning Report","schedule":"0 7 * * 1-5","timezone":"America/Los_Angeles","channel":"general","prompt":"Generate a brief morning status update","model":"fast"}</discord-action>
+\`\`\`
+- \`name\` (required): Human-readable name.
+- \`schedule\` (required): 5-field cron expression (e.g., "0 7 * * 1-5").
+- \`channel\` (required): Target channel name or ID.
+- \`prompt\` (required): The instruction text.
+- \`timezone\` (optional, default: system timezone, or DEFAULT_TIMEZONE env if set): IANA timezone.
+- \`tags\` (optional): Comma-separated purpose tags.
+- \`model\` (optional): "fast" or "capable" (auto-classified if omitted).
+
+**cronUpdate** — Update a cron's settings:
+\`\`\`
+<discord-action>{"type":"cronUpdate","cronId":"cron-a1b2c3d4","schedule":"0 9 * * *","model":"capable"}</discord-action>
+\`\`\`
+- \`cronId\` (required): The stable cron ID.
+- \`schedule\`, \`timezone\`, \`channel\`, \`prompt\`, \`model\`, \`tags\` (optional).
+
+**cronList** — List all cron jobs:
+\`\`\`
+<discord-action>{"type":"cronList"}</discord-action>
+\`\`\`
+
+**cronShow** — Show full details for a cron:
+\`\`\`
+<discord-action>{"type":"cronShow","cronId":"cron-a1b2c3d4"}</discord-action>
+\`\`\`
+
+**cronPause** / **cronResume** — Pause or resume a cron:
+\`\`\`
+<discord-action>{"type":"cronPause","cronId":"cron-a1b2c3d4"}</discord-action>
+<discord-action>{"type":"cronResume","cronId":"cron-a1b2c3d4"}</discord-action>
+\`\`\`
+
+**cronDelete** — Remove a cron job and archive its thread:
+\`\`\`
+<discord-action>{"type":"cronDelete","cronId":"cron-a1b2c3d4"}</discord-action>
+\`\`\`
+Note: cronDelete **archives** the thread (reversible) — it does not permanently
+delete it. The thread history is preserved and the thread can be unarchived later
+via the Discord UI, which will re-register the cron job automatically. Permanent
+thread deletion can only be done manually through Discord.
+
+**cronTrigger** — Immediately execute a cron (manual fire):
+\`\`\`
+<discord-action>{"type":"cronTrigger","cronId":"cron-a1b2c3d4"}</discord-action>
+\`\`\`
+Note: \`force\` overrides are disabled in Discord actions.
+
+**cronSync** — Run full bidirectional sync:
+\`\`\`
+<discord-action>{"type":"cronSync"}</discord-action>
+\`\`\`
+
+**cronTagMapReload** — Reload tag map from disk and optionally trigger sync:
+\`\`\`
+<discord-action>{"type":"cronTagMapReload"}</discord-action>
+\`\`\``;
+}