agent-relay-server 0.62.2 → 0.63.0

package/scripts/orchestrator-spawn-smoke.ts

@@ -20,6 +20,8 @@ type Agent = {
   createdAt?: number;
 };
 
+type ApprovalMode = "open" | "guarded" | "read-only";
+
 const args = process.argv.slice(2);
 let relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
 let orchestratorId = process.env.AGENT_RELAY_SMOKE_ORCHESTRATOR || "";
@@ -92,6 +94,26 @@ function findSpawnedAgent(agents: Agent[], provider: string, label: string, star
     .sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0))[0] || null;
 }
 
+function approvalModesForProvider(provider: string): ApprovalMode[] {
+  if (provider === "claude") return ["open", "guarded", "read-only"];
+  return ["guarded"];
+}
+
+function promptForCase(provider: string, approvalMode: ApprovalMode, label: string, nonce: string): { prompt?: string; nonceLabel?: string } {
+  if (provider !== "claude") return {};
+  if (approvalMode === "guarded") return {};
+  if (approvalMode === "read-only") {
+    return {
+      prompt: `Agent Relay read-only spawn smoke. As your VERY FIRST action, use the Bash tool to run exactly: agent-relay /message label:${label} "${nonce}". Then wait for shutdown — do nothing else.`,
+      nonceLabel: "Bash relay CLI",
+    };
+  }
+  return {
+    prompt: `Agent Relay spawn smoke. As your VERY FIRST action, use the agent-relay MCP tool relay_send_message to send to "label:${label}" with body exactly "${nonce}". Then wait for shutdown — do nothing else.`,
+    nonceLabel: "relay MCP tool",
+  };
+}
+
 const orchestrators = await api<Orchestrator[]>("GET", "/orchestrators");
 // Default selection prefers the orchestrator on the same host as the relay (the
 // gate runs there): a local spawn is faster and avoids cross-host teardown
@@ -123,79 +145,77 @@ for (const provider of providers) {
     continue;
   }
 
-  const label = `smoke-${provider}-${Date.now()}`;
-  const startedAt = Date.now();
-  // #352: for providers seeded with an initial prompt, assert the spawn prompt was actually
-  // DELIVERED and the first turn RAN — by making the prompt's first action a relay tool call
-  // (send a nonce message) and waiting for that nonce to land in the relay feed. Registration
-  // alone (the old smoke) happens via the plugin regardless of prompt delivery, so it never
-  // caught the silently-dropped spawn prompt. The nonce is the end-to-end proof.
-  const nonce = `SMOKE-NONCE-${provider}-${Date.now()}-${Math.round(Math.random() * 1e9).toString(36)}`;
-  const promptProvider = provider === "claude";
-  const prompt = `Agent Relay spawn smoke. As your VERY FIRST action, use the agent-relay MCP tool relay_send_message to send to "label:${label}" with body exactly "${nonce}". Then wait for shutdown — do nothing else.`;
-  console.log(`spawn ${provider} via ${orchestrator.id}`);
-  await api("POST", `/agents/spawn`, {
-    provider,
-    orchestratorId: orchestrator.id,
-    cwd,
-    label,
-    // Prompt-seeded providers must run UNATTENDED: under guarded mode the first-turn relay tool
-    // call would block on a dashboard approval that never comes here. Autonomous workers spawn
-    // open for the same reason. (Approval mode is orthogonal to prompt delivery, which is the
-    // regression under test.)
-    approvalMode: promptProvider ? "open" : "guarded",
-    ...(promptProvider ? { prompt } : {}),
-  });
-
-  let agent: Agent | undefined;
-  let managed: { tmuxSession: string } | undefined;
-  try {
-    agent = await waitFor(`waiting for ${provider} agent registration`, async () => {
-      const agents = await api<Agent[]>("GET", "/agents");
-      return findSpawnedAgent(agents, provider, label, startedAt);
+  for (const approvalMode of approvalModesForProvider(provider)) {
+    const label = `smoke-${provider}-${approvalMode}-${Date.now()}`;
+    const startedAt = Date.now();
+    // #352: for providers seeded with an initial prompt, assert the spawn prompt was actually
+    // DELIVERED and the first turn RAN — by making the prompt's first action send a nonce message
+    // and waiting for that nonce to land in the relay feed. Registration alone happens via the
+    // plugin regardless of prompt delivery, so it never catches silently dropped spawn prompts.
+    const nonce = `SMOKE-NONCE-${provider}-${approvalMode}-${Date.now()}-${Math.round(Math.random() * 1e9).toString(36)}`;
+    const promptCase = promptForCase(provider, approvalMode, label, nonce);
+    console.log(`spawn ${provider} ${approvalMode} via ${orchestrator.id}`);
+    await api("POST", `/agents/spawn`, {
+      provider,
+      orchestratorId: orchestrator.id,
+      cwd,
+      label,
+      approvalMode,
+      ...(promptCase.prompt ? { prompt: promptCase.prompt } : {}),
     });
-    console.log(`registered ${provider}: ${agent.id}`);
 
-    managed = await waitFor(`waiting for ${provider} managed session`, async () => {
-      const latest = (await api<Orchestrator[]>("GET", "/orchestrators")).find((orch) => orch.id === orchestrator.id);
-      return latest?.managedAgents?.find((entry) => entry.label === label || entry.tmuxSession.includes(label)) || null;
-    });
+    let agent: Agent | undefined;
+    let managed: { tmuxSession: string } | undefined;
+    try {
+      agent = await waitFor(`waiting for ${provider} ${approvalMode} agent registration`, async () => {
+        const agents = await api<Agent[]>("GET", "/agents");
+        return findSpawnedAgent(agents, provider, label, startedAt);
+      });
+      console.log(`registered ${provider} ${approvalMode}: ${agent.id}`);
 
-    // Hard-assert the seeded first turn ran and reached relay (the prompt-delivery regression guard).
-    if (promptProvider) {
-      await waitFor(`waiting for ${provider} spawn-prompt first turn (nonce relay tool call)`, async () => {
-        const feed = await api<Array<{ body?: string }>>("GET", "/messages?limit=80");
-        return feed.some((m) => (m.body || "").includes(nonce)) ? true : null;
+      managed = await waitFor(`waiting for ${provider} ${approvalMode} managed session`, async () => {
+        const latest = (await api<Orchestrator[]>("GET", "/orchestrators")).find((orch) => orch.id === orchestrator.id);
+        return latest?.managedAgents?.find((entry) => entry.label === label || entry.tmuxSession.includes(label)) || null;
       });
-      console.log(`spawn-prompt delivered + first turn called relay ${provider}: ${nonce}`);
-    }
-  } finally {
-    // Always tear down — a failed assertion (e.g. a re-introduced prompt-drop) must NOT leak a
-    // managed agent on the host running the gate. Best-effort: teardown errors don't mask the
-    // original failure.
-    if (agent) {
-      const id = agent.id;
-      await api("POST", `/agents/${encodeURIComponent(id)}/actions`, { action: "shutdown" }).catch(() => {});
-      await waitFor(`waiting for ${provider} agent cleanup`, async () => {
-        const current = await apiOptional<Agent>("GET", `/agents/${encodeURIComponent(id)}`);
-        return !current || (current.status === "offline" && current.ready === false) ? true : null;
-      }).catch(() => {});
-      await apiOptional("DELETE", `/agents/${encodeURIComponent(id)}`).catch(() => {});
-      if (managed) {
-        const tmuxSession = managed.tmuxSession;
-        await api("POST", `/orchestrators/${encodeURIComponent(orchestrator.id)}/actions`, {
-          action: "shutdown",
-          agentId: id,
-          tmuxSession,
-          reason: "smoke-cleanup",
-        }).catch(() => {});
-        await waitFor(`waiting for ${provider} managed session cleanup`, async () => {
-          const latest = (await api<Orchestrator[]>("GET", "/orchestrators")).find((orch) => orch.id === orchestrator.id);
-          const stillManaged = latest?.managedAgents?.some((entry) => entry.tmuxSession === tmuxSession || entry.agentId === id);
-          return stillManaged ? null : true;
+
+      // Hard-assert prompt-seeded cases ran and reached relay. Guarded Claude remains
+      // registration-only here: forcing a Bash/MCP first turn would intentionally block on
+      // the known unattended approval path.
+      if (promptCase.nonceLabel) {
+        await waitFor(`waiting for ${provider} ${approvalMode} spawn-prompt first turn (${promptCase.nonceLabel})`, async () => {
+          const feed = await api<Array<{ body?: string }>>("GET", "/messages?limit=80");
+          return feed.some((m) => (m.body || "").includes(nonce)) ? true : null;
+        });
+        console.log(`spawn-prompt delivered + first turn called relay ${provider} ${approvalMode}: ${nonce}`);
+      }
+    } finally {
+      // Always tear down — a failed assertion (e.g. a re-introduced prompt-drop) must NOT leak a
+      // managed agent on the host running the gate. Best-effort: teardown errors don't mask the
+      // original failure.
+      if (agent) {
+        const id = agent.id;
+        await api("POST", `/agents/${encodeURIComponent(id)}/actions`, { action: "shutdown" }).catch(() => {});
+        await waitFor(`waiting for ${provider} ${approvalMode} agent cleanup`, async () => {
+          const current = await apiOptional<Agent>("GET", `/agents/${encodeURIComponent(id)}`);
+          return !current || (current.status === "offline" && current.ready === false) ? true : null;
         }).catch(() => {});
+        await apiOptional("DELETE", `/agents/${encodeURIComponent(id)}`).catch(() => {});
+        if (managed) {
+          const tmuxSession = managed.tmuxSession;
+          await api("POST", `/orchestrators/${encodeURIComponent(orchestrator.id)}/actions`, {
+            action: "shutdown",
+            agentId: id,
+            tmuxSession,
+            reason: "smoke-cleanup",
+          }).catch(() => {});
+          await waitFor(`waiting for ${provider} ${approvalMode} managed session cleanup`, async () => {
+            const latest = (await api<Orchestrator[]>("GET", "/orchestrators")).find((orch) => orch.id === orchestrator.id);
+            const stillManaged = latest?.managedAgents?.some((entry) => entry.tmuxSession === tmuxSession || entry.agentId === id);
+            return stillManaged ? null : true;
+          }).catch(() => {});
+        }
+        console.log(`shutdown ${provider} ${approvalMode}: ${label}`);
       }
-      console.log(`shutdown ${provider}: ${label}`);
     }
   }
 }

package/src/agent-ref.ts

@@ -13,6 +13,7 @@
 
 import { STALE_TTL_MS } from "./config";
 import type { AgentCard, Message, TokenConstraints } from "./types";
+import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
 
 interface ResolveOptions {
   /** Exclude this agent id from matches (e.g. the requester, when pairing). */
@@ -150,12 +151,13 @@ export function resolveAgentRef(ref: string, agents: AgentCard[], opts: ResolveO
 
 export function targetMatchesAgent(target: string, agentId: string, agent?: AgentCard | null): boolean {
   if (!agent) return false;
-  if (target === agentId || target === "broadcast") return true;
-  if (target.startsWith("tag:") && agent.tags.includes(target.slice(4))) return true;
-  if (target.startsWith("cap:") && agent.capabilities.includes(target.slice(4))) return true;
-  if (target.startsWith("label:") && agent.label === target.slice(6)) return true;
-  if (target.startsWith("team:") && agent.teamId === target.slice(5)) return true;
-  return false;
+  return targetMatchesAgentIdentity(target, {
+    id: agentId,
+    label: agent.label,
+    tags: agent.tags,
+    capabilities: agent.capabilities,
+    teamId: agent.teamId,
+  });
 }
 
 export function messageMatchesAgent(msg: Message, agentId: string, agent?: AgentCard | null): boolean {

package/src/automations/constants.ts

@@ -0,0 +1,12 @@
+import type { AutomationCatchUpPolicy, AutomationConcurrencyPolicy, AutomationRunStatus } from "../types";
+
+export const AUTOMATION_KIND = "scheduled_task";
+export const DEFAULT_TIMEZONE = "UTC";
+export const DEFAULT_CATCH_UP: AutomationCatchUpPolicy = "skip";
+export const DEFAULT_CONCURRENCY: AutomationConcurrencyPolicy = "skip";
+export const BLOCKING_RUN_STATUSES = new Set<AutomationRunStatus>(["dispatching", "waiting_agent", "running"]);
+export const OPEN_RUN_STATUSES = new Set<AutomationRunStatus>(["scheduled", "dispatching", "waiting_agent", "running"]);
+export const CLOSED_TASK_STATUS = new Set(["done", "failed", "canceled"]);
+export const MAX_CRON_SCAN_MINUTES = 366 * 24 * 60;
+export const MIN_RUNTIME_BUDGET_MS = 60_000;
+export const MAX_RUNTIME_BUDGET_MS = 24 * 60 * 60 * 1000;

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;
+}