This commit is contained in:
409
packages/agent/src/cron-tools.ts
Normal file
409
packages/agent/src/cron-tools.ts
Normal file
@@ -0,0 +1,409 @@
|
||||
/**
|
||||
* 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<string, unknown> | 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)}`;
|
||||
}
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
Reference in New Issue
Block a user