agent-relay-server 0.62.3 → 0.63.0

package/src/automations/cron.ts

@@ -0,0 +1,129 @@
+import { ValidationError } from "../db";
+import { MAX_CRON_SCAN_MINUTES } from "./constants";
+
+export function validateCron(expression: string, timezone: string): void {
+  parseCron(expression);
+  localParts(Date.now(), timezone);
+}
+
+export function nextScheduledAt(expression: string, timezone: string, afterMs: number): number {
+  const cron = parseCron(expression);
+  let cursor = Math.floor(afterMs / 60_000) * 60_000 + 60_000;
+  for (let i = 0; i < MAX_CRON_SCAN_MINUTES; i += 1) {
+    const parts = localParts(cursor, timezone);
+    if (cronMatches(cron, parts)) return cursor;
+    cursor += 60_000;
+  }
+  throw new ValidationError("schedule has no matching time in the next year");
+}
+
+interface CronSpec {
+  minute: Set<number>;
+  hour: Set<number>;
+  dayOfMonth: Set<number>;
+  month: Set<number>;
+  dayOfWeek: Set<number>;
+  domAny: boolean;
+  dowAny: boolean;
+}
+
+interface LocalTimeParts {
+  minute: number;
+  hour: number;
+  dayOfMonth: number;
+  month: number;
+  dayOfWeek: number;
+}
+
+function parseCron(expression: string): CronSpec {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) throw new ValidationError("schedule must be a 5-field cron expression");
+  const [minute, hour, dom, month, dow] = parts as [string, string, string, string, string];
+  return {
+    minute: parseCronField(minute, 0, 59, "minute"),
+    hour: parseCronField(hour, 0, 23, "hour"),
+    dayOfMonth: parseCronField(dom, 1, 31, "dayOfMonth"),
+    month: parseCronField(month, 1, 12, "month"),
+    dayOfWeek: parseCronField(dow.replace(/\b7\b/g, "0"), 0, 6, "dayOfWeek"),
+    domAny: dom === "*",
+    dowAny: dow === "*",
+  };
+}
+
+function parseCronField(field: string, min: number, max: number, name: string): Set<number> {
+  const values = new Set<number>();
+  for (const rawPart of field.split(",")) {
+    const part = rawPart.trim();
+    if (!part) throw new ValidationError(`${name} cron field is empty`);
+    const [rangePart, stepRaw] = part.split("/");
+    const step = stepRaw === undefined ? 1 : Number(stepRaw);
+    if (!Number.isInteger(step) || step <= 0) throw new ValidationError(`${name} cron step must be a positive integer`);
+    let start: number;
+    let end: number;
+    if (rangePart === "*") {
+      start = min;
+      end = max;
+    } else if (rangePart?.includes("-")) {
+      const [startRaw, endRaw] = rangePart.split("-");
+      start = Number(startRaw);
+      end = Number(endRaw);
+    } else {
+      start = Number(rangePart);
+      end = start;
+    }
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < min || end > max || start > end) {
+      throw new ValidationError(`${name} cron field is out of range`);
+    }
+    for (let value = start; value <= end; value += step) values.add(value);
+  }
+  return values;
+}
+
+// Authoritative localized run date for a dispatched automation task (#480). Formats the
+// scheduled instant in the automation's timezone via the same Intl machinery as cron eval, so
+// scheduled output ("today is ...") never depends on a long-lived agent's stale session context.
+export function formatRunDate(timestamp: number, timezone: string): { iso: string; weekday: string; line: string } {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    weekday: "long",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(timestamp)).map((part) => [part.type, part.value]));
+  const iso = `${parts.year}-${parts.month}-${parts.day}`;
+  const weekday = parts.weekday ?? "";
+  return { iso, weekday, line: `${weekday}, ${iso} (${timezone})` };
+}
+
+function localParts(timestamp: number, timezone: string): LocalTimeParts {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    minute: "numeric",
+    hour: "numeric",
+    hourCycle: "h23",
+    day: "numeric",
+    month: "numeric",
+    weekday: "short",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(timestamp)).map((part) => [part.type, part.value]));
+  const dow = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"].indexOf(parts.weekday ?? "");
+  if (dow < 0) throw new ValidationError(`invalid timezone: ${timezone}`);
+  return {
+    minute: Number(parts.minute),
+    hour: Number(parts.hour),
+    dayOfMonth: Number(parts.day),
+    month: Number(parts.month),
+    dayOfWeek: dow,
+  };
+}
+
+function cronMatches(cron: CronSpec, parts: LocalTimeParts): boolean {
+  if (!cron.minute.has(parts.minute) || !cron.hour.has(parts.hour) || !cron.month.has(parts.month)) return false;
+  const domMatch = cron.dayOfMonth.has(parts.dayOfMonth);
+  const dowMatch = cron.dayOfWeek.has(parts.dayOfWeek);
+  if (cron.domAny && cron.dowAny) return true;
+  if (cron.domAny) return dowMatch;
+  if (cron.dowAny) return domMatch;
+  return domMatch || dowMatch;
+}

package/src/automations/crud.ts

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+import { getOrchestrator, ValidationError } from "../db";
+import { AUTOMATION_KIND } from "./constants";
+import { nextScheduledAt } from "./cron";
+import { db, ensureAutomationTables, getAutomation } from "./storage";
+import { normalizeCreateInput } from "./validation";
+import type { Automation, CreateAutomationInput, UpdateAutomationInput } from "../types";
+
+export function createAutomation(input: CreateAutomationInput, now = Date.now()): Automation {
+  ensureAutomationTables();
+  const normalized = normalizeCreateInput(input);
+  if (!getOrchestrator(normalized.orchestratorId)) throw new ValidationError(`orchestrator ${normalized.orchestratorId} not found`);
+  const id = randomUUID();
+  const nextRunAt = normalized.enabled ? nextScheduledAt(normalized.schedule, normalized.timezone, now) : undefined;
+  db().query(`
+    INSERT INTO automations (id, kind, name, description, enabled, schedule, timezone, next_run_at, catch_up_policy, concurrency_policy, orchestrator_id, target_policy, task_template, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    AUTOMATION_KIND,
+    normalized.name,
+    normalized.description ?? null,
+    normalized.enabled ? 1 : 0,
+    normalized.schedule,
+    normalized.timezone,
+    nextRunAt ?? null,
+    normalized.catchUpPolicy,
+    normalized.concurrencyPolicy,
+    normalized.orchestratorId,
+    JSON.stringify(normalized.targetPolicy),
+    JSON.stringify(normalized.taskTemplate),
+    now,
+    now,
+  );
+  return getAutomation(id)!;
+}
+
+export function updateAutomation(id: string, input: UpdateAutomationInput, now = Date.now()): Automation | null {
+  ensureAutomationTables();
+  const existing = getAutomation(id);
+  if (!existing) return null;
+  const next: CreateAutomationInput = {
+    kind: AUTOMATION_KIND,
+    name: input.name ?? existing.name,
+    description: input.description === null ? undefined : input.description ?? existing.description,
+    enabled: input.enabled ?? existing.enabled,
+    schedule: input.schedule ?? existing.schedule,
+    timezone: input.timezone ?? existing.timezone,
+    catchUpPolicy: input.catchUpPolicy ?? existing.catchUpPolicy,
+    concurrencyPolicy: input.concurrencyPolicy ?? existing.concurrencyPolicy,
+    orchestratorId: input.orchestratorId ?? existing.orchestratorId,
+    targetPolicy: input.targetPolicy ?? existing.targetPolicy,
+    taskTemplate: input.taskTemplate ?? existing.taskTemplate,
+  };
+  const normalized = normalizeCreateInput(next);
+  if (!getOrchestrator(normalized.orchestratorId)) throw new ValidationError(`orchestrator ${normalized.orchestratorId} not found`);
+  const nextRunAt = normalized.enabled ? nextScheduledAt(normalized.schedule, normalized.timezone, now) : undefined;
+  db().query(`
+    UPDATE automations
+    SET name = ?, description = ?, enabled = ?, schedule = ?, timezone = ?, next_run_at = ?,
+        catch_up_policy = ?, concurrency_policy = ?, orchestrator_id = ?, target_policy = ?, task_template = ?, updated_at = ?
+    WHERE id = ?
+  `).run(
+    normalized.name,
+    normalized.description ?? null,
+    normalized.enabled ? 1 : 0,
+    normalized.schedule,
+    normalized.timezone,
+    nextRunAt ?? null,
+    normalized.catchUpPolicy,
+    normalized.concurrencyPolicy,
+    normalized.orchestratorId,
+    JSON.stringify(normalized.targetPolicy),
+    JSON.stringify(normalized.taskTemplate),
+    now,
+    id,
+  );
+  return getAutomation(id)!;
+}
+
+export function deleteAutomation(id: string): boolean {
+  ensureAutomationTables();
+  return db().query("DELETE FROM automations WHERE id = ?").run(id).changes > 0;
+}

package/src/automations/dispatch.ts

@@ -0,0 +1,275 @@
+import { errMessage } from "agent-relay-sdk";
+import { createCommand } from "../commands-db";
+import { getAgentProfile, getSpawnPolicy } from "../config-store";
+import { getOrchestrator, ingestIntegrationEvent, listAgents, ValidationError } from "../db";
+import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { buildSpawnCommand, resolveSpawnModelParams } from "../spawn-command";
+import { nextScheduledAt, formatRunDate } from "./cron";
+import {
+  cancelActiveRuns,
+  db,
+  enqueueAutomationRun,
+  ensureAutomationTables,
+  getAutomation,
+  getAutomationRun,
+  hasActiveRun,
+  insertRun,
+  listAutomations,
+  rowToAutomation,
+  rowToAutomationRun,
+  updateRun,
+  rescheduleAutomation as persistNextRun,
+} from "./storage";
+import type { AutomationDispatchResult } from "./types";
+import type { AgentCard, Automation, AutomationTargetPolicy, ManagedAgent, Orchestrator } from "../types";
+
+export function runDueAutomations(now = Date.now()): AutomationDispatchResult[] {
+  ensureAutomationTables();
+  const results = dispatchQueuedAutomationRuns(now);
+  const due = (db().query("SELECT * FROM automations WHERE enabled = 1 AND next_run_at IS NOT NULL AND next_run_at <= ? ORDER BY next_run_at ASC LIMIT 25").all(now) as any[])
+    .map(rowToAutomation);
+  for (const automation of due) {
+    if (hasActiveRun(automation.id)) {
+      if (automation.concurrencyPolicy === "replace") cancelActiveRuns(automation.id, now, "Replaced by newer scheduled run");
+      else {
+        if (automation.concurrencyPolicy === "queue") enqueueAutomationRun(automation, automation.nextRunAt ?? now, now);
+        rescheduleAutomation(automation, now);
+        continue;
+      }
+    }
+    results.push(dispatchAutomation(automation, automation.nextRunAt ?? now, now));
+    rescheduleAutomation(automation, now);
+  }
+  return results;
+}
+
+export function runAutomationNow(id: string, now = Date.now()): AutomationDispatchResult | null {
+  ensureAutomationTables();
+  const automation = getAutomation(id);
+  if (!automation) return null;
+  if (hasActiveRun(automation.id)) throw new ValidationError("automation already has an active run");
+  return dispatchAutomation(automation, now, now);
+}
+
+function dispatchAutomation(automation: Automation, scheduledFor: number, now: number): AutomationDispatchResult {
+  const run = insertRun(automation, scheduledFor, now);
+  return dispatchAutomationRun(automation, run, now);
+}
+
+function dispatchAutomationRun(automation: Automation, run: ReturnType<typeof getAutomationRun> & NonNullable<unknown>, now: number): AutomationDispatchResult {
+  updateRun(run.id, { status: "dispatching" }, now);
+  try {
+    const orchestrator = requireOnlineOrchestrator(automation.orchestratorId);
+    if (automation.targetPolicy.mode === "existing_agent") {
+      const agent = resolveExistingAgent(automation.targetPolicy, orchestrator);
+      if (!agent && automation.targetPolicy.ifNoMatch !== "spawn") throw new ValidationError("no matching managed agent for automation");
+      if (agent) {
+        const durableTarget = durableExistingAgentTarget(automation.targetPolicy);
+        return createRunTask(automation, run, durableTarget, now, { targetMode: "existing_agent", resolvedAgentId: agent.id });
+      }
+      const fallbackPolicy: AutomationTargetPolicy = { mode: "on_demand_agent", provider: orchestrator.providers[0] ?? "codex", keepAlive: false };
+      return dispatchOnDemandAutomation(automation, run, orchestrator, fallbackPolicy, now);
+    }
+    return dispatchOnDemandAutomation(automation, run, orchestrator, automation.targetPolicy, now);
+  } catch (e) {
+    updateRun(run.id, {
+      status: "failed",
+      finishedAt: now,
+      error: errMessage(e),
+    }, now);
+    return { automation, run: getAutomationRun(run.id)! };
+  }
+}
+
+function dispatchOnDemandAutomation(
+  automation: Automation,
+  run: ReturnType<typeof getAutomationRun> & NonNullable<unknown>,
+  orchestrator: Orchestrator,
+  policy: Extract<AutomationTargetPolicy, { mode: "on_demand_agent" }>,
+  now: number,
+): AutomationDispatchResult {
+  if (!orchestrator.providers.includes(policy.provider)) throw new ValidationError(`orchestrator ${orchestrator.id} does not have provider available: ${policy.provider}`);
+  const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  const label = automationRunLabel(automation.id, run.id);
+  const command = createCommand({
+    type: "agent.spawn",
+    source: "automation",
+    target: orchestrator.agentId,
+    params: buildSpawnCommand({
+      provider: policy.provider,
+      modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort),
+      profile: policy.profile,
+      agentProfile,
+      cwd: policy.cwd || orchestrator.baseDir,
+      workspaceMode: policy.workspaceMode ?? "inherit",
+      label,
+      approvalMode: policy.approvalMode ?? "guarded",
+      requestedBy: "automation",
+      requestedAt: now,
+      automationId: automation.id,
+      automationRunId: run.id,
+      env: runnerRuntimeTokenEnv({
+        orchestratorId: orchestrator.id,
+        cwd: policy.cwd || orchestrator.baseDir,
+        provider: policy.provider,
+        label,
+        createdBy: "automation",
+        profile: policy.profile,
+      }),
+    }),
+  });
+  const result = createRunTask(automation, run, `label:${label}`, now, {
+    targetMode: "on_demand_agent",
+    provider: policy.provider,
+    label,
+    profile: policy.profile,
+    workspaceMode: policy.workspaceMode ?? "inherit",
+  });
+  updateRun(run.id, {
+    status: "waiting_agent",
+    meta: { ...result.run.meta, onDemandLabel: label, spawnCommandId: command.id, workspaceMode: policy.workspaceMode ?? "inherit" },
+  }, now);
+  return { ...result, run: getAutomationRun(run.id)!, command };
+}
+
+function createRunTask(
+  automation: Automation,
+  run: ReturnType<typeof getAutomationRun> & NonNullable<unknown>,
+  target: string,
+  now: number,
+  meta: Record<string, unknown>,
+): AutomationDispatchResult {
+  const template = automation.taskTemplate;
+  // Inject the authoritative dispatch-time run date (#480). A long-lived managed agent's
+  // session-start day awareness goes stale across midnight, so it can't be trusted to derive
+  // "today" - the briefing emitted "Monday Jun 16" when it ran on a Tuesday. The scheduled
+  // instant + timezone are authoritative here; surface them so the task never depends on the
+  // model's recollection. Templates may place it via {{runDate}}/{{runWeekday}}/{{runDateLine}};
+  // otherwise we prepend a Run date line so every scheduled task carries it.
+  const runDate = formatRunDate(run.scheduledFor, automation.timezone);
+  const tokens: Record<string, string> = { runDate: runDate.iso, runWeekday: runDate.weekday, runDateLine: runDate.line };
+  const fill = (text: string) => text.replace(/\{\{\s*(runDate|runWeekday|runDateLine)\s*\}\}/g, (_match, key) => tokens[key] ?? "");
+  const usesRunDateToken = /\{\{\s*(runDate|runWeekday|runDateLine)\s*\}\}/.test(`${template.title}\n${template.body}`);
+  const title = fill(template.title);
+  const body = usesRunDateToken ? fill(template.body) : `Run date: ${runDate.line}.\n\n${template.body}`;
+  const result = ingestIntegrationEvent({
+    source: "automation",
+    type: "scheduled_task",
+    severity: template.severity ?? "info",
+    title,
+    body,
+    target,
+    channel: "automation",
+    // #479 - automation tasks complete via the task-status lifecycle (claim -> done), never a
+    // `/reply`. A reply obligation here is unsatisfiable and re-injects the task into every
+    // successor session when a restart-prone managed agent (e.g. the daily telegram briefing)
+    // mints a new agent id, re-firing the scheduled work off-schedule. Dispatch without one.
+    replyExpected: false,
+    dedupeKey: template.dedupeKey ? `${template.dedupeKey}:${run.id}` : `automation:${automation.id}:run:${run.id}`,
+    externalUrl: template.externalUrl,
+    metadata: {
+      ...(template.metadata ?? {}),
+      automationId: automation.id,
+      automationRunId: run.id,
+      orchestratorId: automation.orchestratorId,
+      runDate: runDate.iso,
+      runWeekday: runDate.weekday,
+      runTimezone: automation.timezone,
+      ...meta,
+    },
+  }, "automation");
+  updateRun(run.id, {
+    status: meta.targetMode === "on_demand_agent" ? "waiting_agent" : "running",
+    startedAt: now,
+    targetAgentId: typeof meta.resolvedAgentId === "string"
+      ? meta.resolvedAgentId
+      : target.startsWith("label:") || target.startsWith("cap:")
+        ? undefined
+        : target,
+    taskId: result.task.id,
+    messageId: result.message?.id,
+    meta,
+  }, now);
+  return { automation, run: getAutomationRun(run.id)!, task: result.task, message: result.message };
+}
+
+function durableExistingAgentTarget(policy: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>): string {
+  const label = policy.selector.label?.trim();
+  if (label) return `label:${label}`;
+  const cap = policy.selector.capabilities?.find((item) => item.trim().length > 0)?.trim();
+  if (cap) return `cap:${cap}`;
+  throw new ValidationError("existing-agent automation target selector must include a label or capability");
+}
+
+function dispatchQueuedAutomationRuns(now: number): AutomationDispatchResult[] {
+  const queued = (db().query(`
+    SELECT r.* FROM automation_runs r
+    JOIN automations a ON a.id = r.automation_id
+    WHERE r.status = 'scheduled' AND a.enabled = 1
+    ORDER BY r.scheduled_for ASC
+    LIMIT 25
+  `).all() as any[]).map(rowToAutomationRun);
+  const results: AutomationDispatchResult[] = [];
+  for (const run of queued) {
+    const automation = getAutomation(run.automationId);
+    if (!automation || hasActiveRun(automation.id)) continue;
+    results.push(dispatchAutomationRun(automation, run, now));
+  }
+  return results;
+}
+
+function rescheduleAutomation(automation: Automation, now: number): void {
+  const next = automation.enabled ? nextScheduledAt(automation.schedule, automation.timezone, now) : undefined;
+  persistNextRun(automation, next, now);
+}
+
+function requireOnlineOrchestrator(orchestratorId: string): Orchestrator {
+  const orchestrator = getOrchestrator(orchestratorId);
+  if (!orchestrator) throw new ValidationError(`orchestrator ${orchestratorId} not found`);
+  if (orchestrator.status !== "online") throw new ValidationError(`orchestrator ${orchestratorId} is ${orchestrator.status}`);
+  return orchestrator;
+}
+
+function resolveExistingAgent(policy: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>, orchestrator: Orchestrator): AgentCard | null {
+  const managedAgentsById = new Map(orchestrator.managedAgents.map((agent) => [agent.agentId, agent]));
+  const managedIds = new Set(managedAgentsById.keys());
+  const candidates = listAgents()
+    .filter((agent) => agent.id !== "user" && agent.id !== "system" && agent.kind !== "channel" && agent.kind !== "orchestrator")
+    .filter((agent) => agent.ready && agent.status !== "offline")
+    .filter((agent) => managedIds.size === 0 || managedIds.has(agent.id))
+    .filter((agent) => automationAgentMatchesSelector(agent, policy.selector, managedAgentsById.get(agent.id)));
+  candidates.sort((a, b) => b.lastSeen - a.lastSeen);
+  return candidates[0] ?? null;
+}
+
+function automationAgentMatchesSelector(
+  agent: AgentCard,
+  selector: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>["selector"],
+  managedAgent?: ManagedAgent,
+): boolean {
+  const policyName = managedAgent?.policyName ?? (typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined);
+  const spawnPolicy = policyName ? getSpawnPolicy(policyName)?.value : undefined;
+  const tags = new Set([...agent.tags, ...stringArray((managedAgent as { tags?: unknown } | undefined)?.tags), ...(spawnPolicy?.tags ?? [])]);
+  const capabilities = new Set([
+    ...agent.capabilities,
+    ...stringArray((managedAgent as { capabilities?: unknown } | undefined)?.capabilities),
+    ...(spawnPolicy?.capabilities ?? []),
+  ]);
+  const label = agent.label ?? managedAgent?.label ?? spawnPolicy?.label;
+  const provider = typeof agent.meta?.provider === "string" ? agent.meta.provider : managedAgent?.provider ?? spawnPolicy?.provider;
+  if (selector.provider) {
+    if (provider !== selector.provider && !tags.has(selector.provider)) return false;
+  }
+  if (selector.label && label !== selector.label) return false;
+  if (selector.tags?.length && !selector.tags.every((tag) => tags.has(tag))) return false;
+  if (selector.capabilities?.length && !selector.capabilities.every((cap) => capabilities.has(cap))) return false;
+  return true;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+function automationRunLabel(automationId: string, runId: string): string {
+  return `automation-${automationId.slice(0, 8)}-${runId.slice(0, 8)}`;
+}

package/src/automations/index.ts

@@ -0,0 +1,5 @@
+export type { AutomationDispatchResult, AutomationReconcileResult } from "./types";
+export { createAutomation, deleteAutomation, updateAutomation } from "./crud";
+export { getAutomation, listAutomationRuns, listAutomations } from "./storage";
+export { runAutomationNow, runDueAutomations } from "./dispatch";
+export { reconcileAutomationRuns } from "./reconcile";