/** * Cron Tools — agent tools for managing cron schedules. * * Tools: * create_schedule — Create a new cron schedule * list_schedules — List all cron schedules * delete_schedule — Delete a schedule by name * trigger_schedule — Manually trigger a schedule * * All tools make HTTP requests to the cron REST API on localhost:3333. */ import type { ToolDefinition } from './tools.js'; const BASE_URL = 'http://127.0.0.1:3333'; /** * Basic cron expression validation. * Accepts 5-field (minute hour dom month dow) and 6-field (with seconds) expressions. * Also accepts common shorthands like @daily, @hourly, @weekly, @monthly, @yearly. */ function isValidCronExpression(expr: string): boolean { const trimmed = expr.trim(); // Allow common shorthand expressions if (/^@(yearly|annually|monthly|weekly|daily|midnight|hourly)$/.test(trimmed)) { return true; } const parts = trimmed.split(/\s+/); // Standard cron: 5 fields (min hour dom month dow) // Extended cron: 6 fields (sec min hour dom month dow) if (parts.length < 5 || parts.length > 6) { return false; } // Each field should contain valid cron characters const cronFieldPattern = /^[\d*,/\-?LW#]+$/; return parts.every(part => cronFieldPattern.test(part)); } /** * #17: heuristic minimum-interval guard for ai_task schedules. A full-agent * turn per firing means real LLM spend — reject expressions that fire more * often than roughly every 5 minutes. Heuristic on the minute field (the * scheduler tick is 60s, so sub-minute precision is unreachable anyway). */ function firesTooOften(expr: string): boolean { const trimmed = expr.trim(); if (/^@(yearly|annually|monthly|weekly|daily|midnight|hourly)$/.test(trimmed)) { return false; } const parts = trimmed.split(/\s+/); // 6-field (seconds) expressions: any non-fixed seconds field fires sub-minute. if (parts.length === 6 && !/^\d+$/.test(parts[0])) { return true; } const minuteField = parts.length === 6 ? parts[1] : parts[0]; // Allowlist, not denylist (ranges like "1-59" and step-on-range forms like // "0-59/2" fire near-every-minute and must not slip through): accept only a // fixed minute, */N with N >= 5, or a comma list of <= 12 fixed minutes. if (/^\d+$/.test(minuteField)) return false; const step = minuteField.match(/^\*\/(\d+)$/); if (step) return Number(step[1]) < 5; const list = minuteField.split(','); if (list.length <= 12 && list.every(p => /^\d+$/.test(p))) return false; return true; } /** * #17: origin of the chat turn that invoked the tool. Snapshotted by * create_schedule so ai_task results can be delivered back to the * originating IM channel — the delivery target is NEVER taken from * free-form tool arguments (pairing-allowlist trust boundary). */ export interface TurnOrigin { session: string; workspace: string | null; channel?: { platform: string; chatId: string }; } export function createCronTools(opts?: { getTurnOrigin?: () => TurnOrigin | null }): ToolDefinition[] { return [ // 1. create_schedule — Create a new cron schedule { name: 'create_schedule', description: 'Create a new cron schedule. Supports standard 5-field cron expressions (minute hour day-of-month month day-of-week) and shorthands like @daily, @hourly. Pass `prompt` to schedule a full agent task (ai_task): the agent re-runs with that prompt on schedule and the result is delivered back to where the schedule was created from.', parameters: { type: 'object', properties: { name: { type: 'string', description: 'Human-readable name for the schedule (e.g., "Daily memory cleanup")', }, cron_expression: { type: 'string', description: 'Cron expression (e.g., "0 3 * * *" for daily at 3am, "*/15 * * * *" for every 15 minutes). ai_task schedules (with `prompt`) may not fire more often than every 5 minutes.', }, job_type: { type: 'string', enum: ['agent_task', 'memory_consolidation', 'workspace_health'], description: 'Type of job to run (default: agent_task)', }, job_data: { type: 'string', description: 'Optional JSON string with job configuration data', }, workspace_id: { type: 'string', description: 'Workspace ID (required for agent_task type; defaults to the current workspace when scheduling an ai_task)', }, prompt: { type: 'string', description: 'ai_task mode (#17): the prompt the agent runs on each firing as a full agent turn (tools + memory, approval-gated writes HELD). Only valid for agent_task schedules.', }, once: { type: 'boolean', description: 'ai_task only: disable the schedule after its first successful run (one-shot).', }, deliver: { type: 'string', enum: ['origin', 'notification'], description: "ai_task only: 'origin' (default) delivers the result back to the originating IM channel when the schedule was created from one; 'notification' only emits a desktop notification.", }, }, required: ['name', 'cron_expression'], }, execute: async (args) => { const name = args.name as string; const cronExpr = args.cron_expression as string; const jobType = (args.job_type as string) || 'agent_task'; const jobData = args.job_data as string | undefined; let workspaceId = args.workspace_id as string | undefined; const prompt = args.prompt as string | undefined; const once = args.once as boolean | undefined; const deliver = (args.deliver as string | undefined) ?? 'origin'; // Validate cron expression format if (!isValidCronExpression(cronExpr)) { return `Error: Invalid cron expression "${cronExpr}". Expected 5-field format (minute hour day-of-month month day-of-week) or a shorthand like @daily, @hourly.`; } // Parse optional job data JSON let jobConfig: Record | undefined; if (jobData) { try { jobConfig = JSON.parse(jobData); } catch { return `Error: Invalid JSON in job_data: "${jobData}"`; } // #17 SEC: mode/deliverTo/once are executor-internal and settable // ONLY via the typed params below (deliverTo exclusively from the // trusted origin snapshot). Free-form job_data must not smuggle // them — otherwise the agent could route ai_task output to an // arbitrary, unpaired chat. if (jobConfig) { delete jobConfig.mode; delete jobConfig.deliverTo; delete jobConfig.once; } } // #17 ai_task: an explicit `prompt` upgrades the schedule to a full // agent turn per firing. Delivery target comes from the trusted // turn-origin snapshot, never from tool args. if (prompt !== undefined) { if (jobType !== 'agent_task') { return 'Error: `prompt` is only valid for agent_task schedules.'; } if (firesTooOften(cronExpr)) { return `Error: ai_task schedules may not fire more often than every 5 minutes (got "${cronExpr}"). Use a wider interval like "*/15 * * * *".`; } const origin = opts?.getTurnOrigin?.() ?? null; jobConfig = { ...(jobConfig ?? {}), prompt, mode: 'ai_task', ...(once ? { once: true } : {}), ...(deliver === 'origin' && origin?.channel ? { deliverTo: origin.channel } : {}), }; if (!workspaceId && origin?.workspace) { workspaceId = origin.workspace; } } try { const response = await fetch(`${BASE_URL}/api/cron`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name, cronExpr, jobType, jobConfig, workspaceId, }), }); if (!response.ok) { const err = await response.json().catch(() => ({ error: response.statusText })); return `Failed to create schedule: ${(err as { error?: string }).error || response.statusText}`; } const created = (await response.json()) as { id: number; name: string; cronExpr: string; jobType: string; nextRunAt: string | null; enabled: boolean; }; const nextRun = created.nextRunAt ? new Date(created.nextRunAt).toLocaleString() : 'unknown'; return [ `Schedule created successfully.`, ``, `- **Name**: ${created.name}`, `- **Expression**: \`${created.cronExpr}\``, `- **Job type**: ${created.jobType}`, `- **Enabled**: ${created.enabled ? 'yes' : 'no'}`, `- **Next run**: ${nextRun}`, `- **ID**: ${created.id}`, ].join('\n'); } catch (err) { return `Error creating schedule: ${err instanceof Error ? err.message : String(err)}`; } }, }, // 2. list_schedules — List all cron schedules { name: 'list_schedules', description: 'List all cron schedules with their expression, next run time, and enabled status.', parameters: { type: 'object', properties: {}, }, execute: async () => { try { const response = await fetch(`${BASE_URL}/api/cron`); if (!response.ok) { const err = await response.json().catch(() => ({ error: response.statusText })); return `Failed to list schedules: ${(err as { error?: string }).error || response.statusText}`; } const data = (await response.json()) as { schedules: Array<{ id: number; name: string; cronExpr: string; jobType: string; enabled: boolean; lastRunAt: string | null; nextRunAt: string | null; }>; count: number; }; if (data.count === 0) { return 'No cron schedules configured.'; } const lines: string[] = [ `## Cron Schedules (${data.count})`, '', '| # | Name | Expression | Job Type | Enabled | Next Run |', '|---|------|------------|----------|---------|----------|', ]; for (const [i, s] of data.schedules.entries()) { const nextRun = s.nextRunAt ? new Date(s.nextRunAt).toLocaleString() : '—'; const enabled = s.enabled ? 'yes' : 'no'; lines.push( `| ${i + 1} | ${s.name} | \`${s.cronExpr}\` | ${s.jobType} | ${enabled} | ${nextRun} |`, ); } return lines.join('\n'); } catch (err) { return `Error listing schedules: ${err instanceof Error ? err.message : String(err)}`; } }, }, // 3. delete_schedule — Delete a schedule by name { name: 'delete_schedule', description: 'Delete a cron schedule by name. Finds the schedule by name, then deletes it by ID.', parameters: { type: 'object', properties: { name: { type: 'string', description: 'Name of the schedule to delete', }, }, required: ['name'], }, execute: async (args) => { const name = args.name as string; try { // Step 1: List all schedules and find by name const listResp = await fetch(`${BASE_URL}/api/cron`); if (!listResp.ok) { return `Failed to list schedules: ${listResp.statusText}`; } const listData = (await listResp.json()) as { schedules: Array<{ id: number; name: string }>; }; const match = listData.schedules.find( s => s.name.toLowerCase() === name.toLowerCase(), ); if (!match) { return `Schedule "${name}" not found. Use \`list_schedules\` to see available schedules.`; } // Step 2: Delete by ID const delResp = await fetch(`${BASE_URL}/api/cron/${match.id}`, { method: 'DELETE', }); if (!delResp.ok) { const err = await delResp.json().catch(() => ({ error: delResp.statusText })); return `Failed to delete schedule: ${(err as { error?: string }).error || delResp.statusText}`; } return `Schedule "${match.name}" (ID: ${match.id}) deleted successfully.`; } catch (err) { return `Error deleting schedule: ${err instanceof Error ? err.message : String(err)}`; } }, }, // 4. trigger_schedule — Manually trigger a schedule { name: 'trigger_schedule', description: 'Manually trigger a cron schedule by name. Runs the scheduled job immediately.', parameters: { type: 'object', properties: { name: { type: 'string', description: 'Name of the schedule to trigger', }, }, required: ['name'], }, execute: async (args) => { const name = args.name as string; try { // Step 1: List all schedules and find by name const listResp = await fetch(`${BASE_URL}/api/cron`); if (!listResp.ok) { return `Failed to list schedules: ${listResp.statusText}`; } const listData = (await listResp.json()) as { schedules: Array<{ id: number; name: string }>; }; const match = listData.schedules.find( s => s.name.toLowerCase() === name.toLowerCase(), ); if (!match) { return `Schedule "${name}" not found. Use \`list_schedules\` to see available schedules.`; } // Step 2: Trigger by ID const triggerResp = await fetch( `${BASE_URL}/api/cron/${match.id}/trigger`, { method: 'POST' }, ); if (!triggerResp.ok) { const err = await triggerResp.json().catch(() => ({ error: triggerResp.statusText })); return `Failed to trigger schedule: ${(err as { error?: string }).error || triggerResp.statusText}`; } const result = (await triggerResp.json()) as { triggered: boolean; id: number; nextRunAt?: string; }; const nextRun = result.nextRunAt ? new Date(result.nextRunAt).toLocaleString() : 'unknown'; return `Schedule "${match.name}" triggered successfully. Next run: ${nextRun}`; } catch (err) { return `Error triggering schedule: ${err instanceof Error ? err.message : String(err)}`; } }, }, ]; }