agent-relay-server 0.88.2 → 0.89.0

package/src/maintenance/teams.ts

@@ -66,6 +66,7 @@ function detectSilentMembers(
     watch.set(member.id, {
       lastActiveAt: Math.max(member.lastSeen, existing?.lastActiveAt ?? 0),
       pinged: recovered ? false : existing?.pinged ?? false,
+      epoch: member.epoch,
       ...(member.label ? { label: member.label } : {}),
     });
   }
@@ -77,7 +78,9 @@ function detectSilentMembers(
     entry.pinged = true;
     // A terminal event already fired — a #633 crash report (death) or a #645 clean terminus
     // (transient reap after land / graceful shutdown). Either way this is not a silent death.
-    if (getCrashReport(memberId) || hasTerminalEvent(memberId)) continue;
+    // #652: only suppress when the terminal event's epoch matches the member's observed epoch —
+    // a stale event from a prior epoch must not mask a real death in the current epoch.
+    if (getCrashReport(memberId) || hasTerminalEvent(memberId, entry.epoch)) continue;
     if (!coordinatorId) continue;
     const minutes = Math.floor(gapMs / 60_000);
     notifyTarget(
@@ -124,6 +127,7 @@ function detectGoneCoordinator(
       coordinatorId,
       lastActiveAt: Math.max(coord.lastSeen, prior?.lastActiveAt ?? 0),
       escalated: false, // alive again ⇒ re-arm the escalation
+      epoch: coord.epoch,
       ...(coord.label ? { label: coord.label } : {}),
     });
     return;
@@ -138,7 +142,8 @@ function detectGoneCoordinator(
 
   // A terminal marker means a #645 clean terminus (graceful shutdown) or a #633 crash the operator was
   // already surfaced on — not a SILENT death. Suppress.
-  if (getCrashReport(coordinatorId) || hasTerminalEvent(coordinatorId)) {
+  // #652: only suppress when the terminal event's epoch matches the coordinator's observed epoch.
+  if (getCrashReport(coordinatorId) || hasTerminalEvent(coordinatorId, watch.epoch)) {
     out.suppressedTeamIds.push(teamId);
     return;
   }

package/src/mcp/index.ts

@@ -18,6 +18,7 @@ import type { JsonRpcId, JsonRpcRequest, McpAuthContext, ToolDefinition } from "
 import { positiveIdOrUndefined, recordField, stringField } from "./validation";
 import { IDENTITY_TOOLS, hasAnyScope, mcpAuthContext, relayCompactAndResume, relayRecall, relayWhoami } from "./identity";
 import { MESSAGING_TOOLS, relayAgentCrashReport, relayAgentStatus, relayAttachArtifact, relayFindAgents, relayGetMessage, relayGetThread, relayReply, relaySendMessage, relayUploadArtifact } from "./tools-messaging";
+import { SCHEDULER_TOOLS, relayCancelTimer, relayListTimers, relayScheduleTimer } from "./tools-scheduler";
 import { SPAWN_TOOLS, relayMyAgents, relayShutdownAgent, relaySpawnAgent, relaySpawnTargets } from "./tools-spawn";
 import { WORKSPACE_TOOLS, callerIsolatedWorkspace, relayWorkspaceList, relayWorkspaceMutation, relayWorkspaceStatus } from "./tools-workspace";
 
@@ -25,6 +26,7 @@ const MCP_PROTOCOL_VERSION = "2024-11-05";
 const MCP_BODY_OVERHEAD_BYTES = 16 * 1024;
 const TOOLS: ToolDefinition[] = [
   ...MESSAGING_TOOLS,
+  ...SCHEDULER_TOOLS,
   ...IDENTITY_TOOLS,
   ...SPAWN_TOOLS,
   AGENT_ACTION_TOOL,
@@ -121,6 +123,9 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_reply") result = relayReply(auth, args);
     else if (name === "relay_get_message") result = relayGetMessage(args);
     else if (name === "relay_get_thread") result = relayGetThread(args);
+    else if (name === "relay_schedule_timer") result = relayScheduleTimer(auth, args);
+    else if (name === "relay_list_timers") result = relayListTimers(auth, args);
+    else if (name === "relay_cancel_timer") result = relayCancelTimer(auth, args);
     else if (name === "relay_upload_artifact") result = await relayUploadArtifact(auth, args);
     else if (name === "relay_attach_artifact") result = relayAttachArtifact(auth, args);
     else if (name === "relay_agent_status") result = relayAgentStatus(args);

package/src/mcp/tools-messaging.ts

@@ -30,11 +30,12 @@ import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { authContextFromMcp } from "../services/auth-context";
 import { ServiceAuthError } from "../services/errors";
 import { sendMessageService } from "../services/send-message";
+import { scheduleTimer } from "../services/scheduler";
 import { optionalEnum } from "../validation";
 import { isRecord } from "agent-relay-sdk";
 import type { ArtifactKind, ArtifactSensitivity, AttachmentRef, Message, SendMessageInput } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
-import { callerAgentId } from "./identity";
+import { callerAgentId, hasScope } from "./identity";
 import { enumField, optionalAttachments, optionalBoolean, optionalFutureTimestamp, optionalNonNegativeInt, optionalPositiveInt, optionalRecord, optionalString, positiveId, recordField, stringField } from "./validation";
 
 const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive", "other"] as const;
@@ -57,6 +58,7 @@ export const MESSAGING_TOOLS: ToolDefinition[] = [
         channel: { type: "string" },
         claimable: { type: "boolean" },
         idempotencyKey: { type: "string" },
+        deliveryTime: { type: "string", description: "Optional future ISO timestamp. When set, relay_send_message creates a one-shot durable timer instead of sending immediately. Requires schedule:write." },
         attachments: { type: "array", items: { type: "object" } },
         payload: { type: "object" },
         meta: { type: "object" },
@@ -221,9 +223,27 @@ function runMcpSend(auth: McpAuthContext, input: SendMessageInput): Message & {
   }
 }
 
-export function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
+export function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): (Message & { delivery: DeliveryReceipt }) | Record<string, unknown> {
   const attachments = optionalAttachments(args.attachments);
   const payload = payloadWithAttachments(optionalRecord(args.payload, "payload"), attachments);
+  const deliveryTime = optionalString(args.deliveryTime, "deliveryTime", 80);
+  if (deliveryTime) {
+    if (!hasScope(auth, "schedule:write")) throw new McpAuthError("deliveryTime requires schedule:write");
+    try {
+      const timer = scheduleTimer({
+        target: stringField(args.to, "to", { required: true, max: 200 }),
+        at: deliveryTime,
+        body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
+        subject: optionalString(args.subject, "subject", 200),
+        payload,
+        idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
+      }, authContextFromMcp({ kind: auth.kind, actor: auth.actor, scopes: auth.scopes, component: auth.component }));
+      return { scheduled: true, timer };
+    } catch (e) {
+      if (e instanceof ServiceAuthError) throw new McpAuthError(e.message);
+      throw e;
+    }
+  }
   const input: SendMessageInput = {
     from: optionalString(args.from, "from", 200) ?? "",
     to: stringField(args.to, "to", { required: true, max: 200 }),

package/src/mcp/tools-scheduler.ts

@@ -0,0 +1,135 @@
+import { McpAuthError } from "../mcp-errors";
+import { authContextFromMcp } from "../services/auth-context";
+import { ServiceAuthError } from "../services/errors";
+import { cancelTimer, listTimers, scheduleTimer, type ScheduleTimerInput } from "../services/scheduler";
+import type { ScheduledTimer } from "../db";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { optionalBoolean, optionalPositiveInt, optionalRecord, optionalString, stringField } from "./validation";
+
+export const SCHEDULER_TOOLS: ToolDefinition[] = [
+  {
+    name: "relay_schedule_timer",
+    description: "Create a durable Relay timer that wakes a target by enqueueing a normal Relay message when due. Supports one-shot afterMs/at and fixed recurring everyMs. RRULE is intentionally deferred.",
+    requiredScopes: ["schedule:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Defaults to me. Supports agent id, policy:name, label:x, channel targets, and other normal Relay targets." },
+        afterMs: { type: "integer", minimum: 1 },
+        at: { type: "string", description: "Future ISO timestamp." },
+        everyMs: { type: "integer", minimum: 1 },
+        subject: { type: "string" },
+        body: { type: "string" },
+        payload: { type: "object" },
+        maxRuns: { type: "integer", minimum: 1 },
+        expiresAt: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["body"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_list_timers",
+    description: "List your durable Relay timers. Admin callers may pass createdBy to inspect another creator.",
+    requiredScopes: ["schedule:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeDisabled: { type: "boolean" },
+        limit: { type: "integer", minimum: 1, maximum: 500 },
+        createdBy: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_cancel_timer",
+    description: "Cancel one of your durable Relay timers. Admin callers may cancel any timer.",
+    requiredScopes: ["schedule:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        timerId: { type: "string" },
+      },
+      required: ["timerId"],
+      additionalProperties: false,
+    },
+  },
+];
+
+export function relayScheduleTimer(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  return withAuthErrors(() => ({
+    timer: serializeTimer(scheduleTimer(cleanScheduleInput(args), authContextFromMcp(authContextPayload(auth)))),
+  }));
+}
+
+export function relayListTimers(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  return withAuthErrors(() => {
+    const timers = listTimers(authContextFromMcp(authContextPayload(auth)), {
+      includeDisabled: optionalBoolean(args.includeDisabled, "includeDisabled"),
+      limit: optionalPositiveInt(args.limit, "limit"),
+      createdBy: optionalString(args.createdBy, "createdBy", 200),
+    });
+    return { timers: timers.map(serializeTimer), count: timers.length };
+  });
+}
+
+export function relayCancelTimer(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  return withAuthErrors(() => ({
+    timer: serializeTimer(cancelTimer(stringField(args.timerId, "timerId", { required: true, max: 120 }), authContextFromMcp(authContextPayload(auth)))),
+  }));
+}
+
+function cleanScheduleInput(args: Record<string, unknown>): ScheduleTimerInput {
+  return {
+    target: optionalString(args.target, "target", 200),
+    afterMs: optionalPositiveInt(args.afterMs, "afterMs"),
+    at: optionalString(args.at, "at", 80),
+    everyMs: optionalPositiveInt(args.everyMs, "everyMs"),
+    subject: optionalString(args.subject, "subject", 200),
+    body: stringField(args.body, "body", { required: true }),
+    payload: optionalRecord(args.payload, "payload"),
+    maxRuns: optionalPositiveInt(args.maxRuns, "maxRuns"),
+    expiresAt: typeof args.expiresAt === "number" ? args.expiresAt : optionalString(args.expiresAt, "expiresAt", 80),
+    idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
+  };
+}
+
+function authContextPayload(auth: McpAuthContext): Parameters<typeof authContextFromMcp>[0] {
+  return { kind: auth.kind, actor: auth.actor, scopes: auth.scopes, component: auth.component };
+}
+
+function serializeTimer(timer: ScheduledTimer): Record<string, unknown> {
+  return {
+    id: timer.id,
+    target: timer.target,
+    createdBy: timer.createdBy,
+    createdAt: timer.createdAt,
+    nextRunAt: timer.nextRunAt,
+    scheduleKind: timer.scheduleKind,
+    scheduleDef: timer.scheduleDef,
+    subject: timer.subject,
+    body: timer.body,
+    payload: timer.payload,
+    enabled: timer.enabled,
+    runCount: timer.runCount,
+    maxRuns: timer.maxRuns,
+    expiresAt: timer.expiresAt,
+    lastRunAt: timer.lastRunAt,
+    lastError: timer.lastError,
+    consecutiveFailures: timer.consecutiveFailures,
+    idempotencyKey: timer.idempotencyKey,
+    correlationId: timer.correlationId,
+    lastMessageId: timer.lastMessageId,
+  };
+}
+
+function withAuthErrors<T>(fn: () => T): T {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof ServiceAuthError) throw new McpAuthError(error.message);
+    throw error;
+  }
+}

package/src/notification-types.ts

@@ -4,6 +4,7 @@ export type NotificationType =
   | "agent.ready"
   | "agent.exited"
   | "agent.spawn_failed"
+  | "agent.spawn_recovered"
   | "agent.context_threshold"
   | "agent.stuck_busy"
   | "agent.quota_threshold"
@@ -59,6 +60,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.ready": null,
   "agent.exited": null,
   "agent.spawn_failed": null,
+  "agent.spawn_recovered": null,
   "agent.context_threshold": 15 * MINUTES,
   "agent.stuck_busy": null,
   "agent.quota_threshold": 15 * MINUTES,

package/src/quota-advisory.ts

@@ -7,15 +7,17 @@ import { parseJson } from "./utils";
 import { setProviderQuotaAdvisoryHandler, type ProviderQuotaAdvisoryInput } from "./db/provider-quotas.ts";
 import type { QuotaState } from "./types";
 
+type QuotaAdvisoryStage = "warn" | "critical" | "reset";
+
 interface QuotaAdvisoryWindowState {
   lastQuotaAdvisoryBand?: number;
+  lastQuotaAdvisoryStage?: QuotaAdvisoryStage;
   lastQuotaAdvisoryAt?: number;
   lastRemainingPercent?: number;
   lastResetsAt?: number;
 }
 
 type QuotaAdvisoryState = Record<string, QuotaAdvisoryWindowState>;
-type QuotaAdvisoryStage = "warn" | "critical" | "reset";
 
 type AgentRecipientRow = {
   id: string;
@@ -45,7 +47,7 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
     const remaining = quotaRemaining(window.utilization);
     const remainingPercent = percent(remaining);
     const previous = nextState[window.name];
-    const reset = previous?.lastQuotaAdvisoryBand !== undefined && isQuotaReset(remaining, previousWindow, window, config.resetRemaining);
+    const reset = hasLastQuotaAdvisory(previous) && isQuotaReset(remaining, previousWindow, window, config.resetRemaining);
     if (reset) {
       notifyQuotaAdvisory({
         provider: input.provider,
@@ -69,8 +71,8 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
     }
 
     const band = quotaRemainingBand(remaining, config.bandSize);
-    if (previous?.lastQuotaAdvisoryBand === band) continue;
     const stage: QuotaAdvisoryStage = remaining - config.criticalRemaining <= QUOTA_THRESHOLD_EPSILON ? "critical" : "warn";
+    if (lastQuotaAdvisoryStage(previous, config.criticalRemaining) === stage) continue;
     notifyQuotaAdvisory({
       provider: input.provider,
       accountKey: input.accountKey,
@@ -85,6 +87,7 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
     });
     nextState[window.name] = {
       lastQuotaAdvisoryBand: band,
+      lastQuotaAdvisoryStage: stage,
       lastQuotaAdvisoryAt: input.now,
       lastRemainingPercent: remainingPercent,
       ...(window.resetsAt !== undefined ? { lastResetsAt: window.resetsAt } : {}),
@@ -94,6 +97,27 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
   return JSON.stringify(nextState);
 }
 
+function hasLastQuotaAdvisory(previous: QuotaAdvisoryWindowState | undefined): boolean {
+  return previous?.lastQuotaAdvisoryStage !== undefined || previous?.lastQuotaAdvisoryBand !== undefined;
+}
+
+function lastQuotaAdvisoryStage(
+  previous: QuotaAdvisoryWindowState | undefined,
+  criticalRemaining: number,
+): QuotaAdvisoryStage | undefined {
+  if (!previous) return undefined;
+  if (previous.lastQuotaAdvisoryStage === "warn" || previous.lastQuotaAdvisoryStage === "critical") {
+    return previous.lastQuotaAdvisoryStage;
+  }
+  if (typeof previous.lastRemainingPercent === "number") {
+    return previous.lastRemainingPercent <= percent(criticalRemaining) ? "critical" : "warn";
+  }
+  if (typeof previous.lastQuotaAdvisoryBand === "number") {
+    return previous.lastQuotaAdvisoryBand <= percent(criticalRemaining) ? "critical" : "warn";
+  }
+  return undefined;
+}
+
 function notifyQuotaAdvisory(input: {
   provider: string;
   accountKey: string;

package/src/services/scheduler.ts

@@ -0,0 +1,303 @@
+import { randomUUID } from "node:crypto";
+import { errMessage } from "agent-relay-sdk";
+import { hasScope } from "agent-relay-sdk/types";
+import {
+  MAX_BODY_BYTES,
+  SCHEDULER_CLAIM_LEASE_MS,
+  SCHEDULER_MAX_ACTIVE_TIMERS,
+  SCHEDULER_MAX_FAILURES,
+  SCHEDULER_MAX_PAYLOAD_BYTES,
+  SCHEDULER_MIN_RECURRING_INTERVAL_MS,
+  SCHEDULER_RETRY_MS,
+  SCHEDULER_TICK_MS,
+} from "../config";
+import {
+  ValidationError,
+  cancelScheduledTimer,
+  claimScheduledTimer,
+  completeScheduledTimerRun,
+  countActiveScheduledTimers,
+  disableScheduledTimer,
+  getScheduledTimer,
+  insertScheduledTimer,
+  listDueScheduledTimerIds,
+  listScheduledTimers,
+  recordScheduledTimerFailure,
+  type ScheduledTimer,
+  type TimerScheduleDef,
+  type TimerScheduleKind,
+} from "../db";
+import type { ComponentToken, SendMessageInput } from "../types";
+import { ServiceAuthError } from "./errors";
+import type { AuthContext } from "./auth-context";
+import { sendMessageService, validateSendMessageAuthorization } from "./send-message";
+
+export interface ScheduleTimerInput {
+  target?: string;
+  afterMs?: number;
+  at?: string;
+  everyMs?: number;
+  rrule?: string;
+  timezone?: string;
+  subject?: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  maxRuns?: number;
+  expiresAt?: string | number;
+  idempotencyKey?: string;
+}
+
+export interface RunDueTimersResult {
+  claimed: number;
+  fired: number;
+  failed: number;
+  disabled: number;
+  messageIds: number[];
+}
+
+let schedulerTimer: Timer | undefined;
+
+export function startRelayScheduler(): void {
+  if (schedulerTimer) return;
+  void runDueScheduledTimers().catch((error) => console.warn(`relay scheduler tick failed: ${errMessage(error)}`));
+  schedulerTimer = setInterval(() => {
+    void runDueScheduledTimers().catch((error) => console.warn(`relay scheduler tick failed: ${errMessage(error)}`));
+  }, SCHEDULER_TICK_MS);
+}
+
+export function stopRelaySchedulerForTests(): void {
+  if (schedulerTimer) clearInterval(schedulerTimer);
+  schedulerTimer = undefined;
+}
+
+export function scheduleTimer(input: ScheduleTimerInput, ctx: AuthContext): ScheduledTimer {
+  const now = Date.now();
+  const schedule = normalizeSchedule(input, now);
+  const target = normalizeTarget(input.target, ctx);
+  const createdBy = ctx.callerAgentId ?? ctx.actor.id;
+  const deliveryFrom = ctx.callerAgentId ?? "system";
+  const body = cleanBody(input.body);
+  const payload = cleanPayload(input.payload);
+  const maxRuns = cleanPositiveInt(input.maxRuns, "maxRuns");
+  const expiresAt = cleanExpiresAt(input.expiresAt, now);
+  const idempotencyKey = cleanOptionalString(input.idempotencyKey, "idempotencyKey", 240);
+
+  if (schedule.kind === "interval") {
+    if ((schedule.def.everyMs ?? 0) < SCHEDULER_MIN_RECURRING_INTERVAL_MS) {
+      throw new ValidationError(`everyMs must be at least ${SCHEDULER_MIN_RECURRING_INTERVAL_MS}`);
+    }
+    if (!maxRuns && !expiresAt && !canCreatePersistentTimer(ctx)) {
+      throw new ServiceAuthError("recurring timers require maxRuns, expiresAt, or schedule:persistent");
+    }
+  }
+  if (expiresAt !== undefined && expiresAt <= schedule.nextRunAt) {
+    throw new ValidationError("expiresAt must be after the first run");
+  }
+  if (countActiveScheduledTimers(createdBy) >= SCHEDULER_MAX_ACTIVE_TIMERS) {
+    throw new ServiceAuthError(`active timer quota exceeded (${SCHEDULER_MAX_ACTIVE_TIMERS})`);
+  }
+
+  validateSendMessageAuthorization({
+    from: deliveryFrom,
+    to: target,
+    body,
+    subject: cleanOptionalString(input.subject, "subject", 200),
+    payload,
+    idempotencyKey: idempotencyKey ? `${idempotencyKey}:probe` : undefined,
+  }, ctx);
+
+  return insertScheduledTimer({
+    target,
+    createdBy,
+    createdByKind: ctx.actor.kind,
+    createdByScopes: ctx.scopes,
+    createdByConstraints: ctx.constraints,
+    deliveryFrom,
+    nextRunAt: schedule.nextRunAt,
+    scheduleKind: schedule.kind,
+    scheduleDef: schedule.def,
+    subject: cleanOptionalString(input.subject, "subject", 200),
+    body,
+    payload,
+    maxRuns,
+    expiresAt,
+    idempotencyKey,
+  }, now);
+}
+
+export function listTimers(ctx: AuthContext, input: { includeDisabled?: boolean; limit?: number; createdBy?: string } = {}): ScheduledTimer[] {
+  const admin = canAdministerTimers(ctx);
+  const createdBy = admin ? input.createdBy : (ctx.callerAgentId ?? ctx.actor.id);
+  return listScheduledTimers({
+    createdBy,
+    includeDisabled: input.includeDisabled,
+    limit: input.limit,
+  });
+}
+
+export function cancelTimer(id: string, ctx: AuthContext): ScheduledTimer {
+  const timer = getScheduledTimer(id);
+  if (!timer) throw new ValidationError(`timer ${id} not found`);
+  if (!canAdministerTimers(ctx) && timer.createdBy !== (ctx.callerAgentId ?? ctx.actor.id)) {
+    throw new ServiceAuthError("cannot cancel a timer created by another caller");
+  }
+  return cancelScheduledTimer(id) ?? timer;
+}
+
+export async function runDueScheduledTimers(input: { now?: number; limit?: number; owner?: string } = {}): Promise<RunDueTimersResult> {
+  const now = input.now ?? Date.now();
+  const owner = input.owner ?? `${process.pid}-${randomUUID()}`;
+  const ids = listDueScheduledTimerIds(now, input.limit ?? 25);
+  const result: RunDueTimersResult = { claimed: 0, fired: 0, failed: 0, disabled: 0, messageIds: [] };
+  for (const id of ids) {
+    const timer = claimScheduledTimer(id, owner, now, SCHEDULER_CLAIM_LEASE_MS);
+    if (!timer) continue;
+    result.claimed += 1;
+    const fired = fireClaimedTimer(timer, now);
+    if (fired.status === "fired") {
+      result.fired += 1;
+      result.messageIds.push(fired.messageId);
+    } else if (fired.status === "disabled") {
+      result.disabled += 1;
+    } else {
+      result.failed += 1;
+    }
+  }
+  return result;
+}
+
+function fireClaimedTimer(timer: ScheduledTimer, now: number): { status: "fired"; messageId: number } | { status: "failed" | "disabled" } {
+  if (timer.expiresAt !== undefined && timer.expiresAt <= now) {
+    disableScheduledTimer(timer.id, "timer expired before delivery");
+    return { status: "disabled" };
+  }
+  try {
+    const runNumber = timer.runCount + 1;
+    const result = sendMessageService({
+      from: timer.deliveryFrom,
+      to: timer.target,
+      subject: timer.subject,
+      body: timer.body,
+      payload: {
+        ...timer.payload,
+        scheduler: {
+          timerId: timer.id,
+          correlationId: timer.correlationId,
+          run: runNumber,
+        },
+      },
+      meta: {
+        scheduler: {
+          timerId: timer.id,
+          correlationId: timer.correlationId,
+          run: runNumber,
+        },
+      },
+      idempotencyKey: timerRunIdempotencyKey(timer, runNumber),
+    } satisfies SendMessageInput, persistedAuthContext(timer));
+    completeScheduledTimerRun({ timer, messageId: result.message.id, now });
+    return { status: "fired", messageId: result.message.id };
+  } catch (error) {
+    const updated = recordScheduledTimerFailure({
+      id: timer.id,
+      error: errMessage(error),
+      now,
+      retryMs: SCHEDULER_RETRY_MS,
+      maxFailures: SCHEDULER_MAX_FAILURES,
+    });
+    return updated?.enabled ? { status: "failed" } : { status: "disabled" };
+  }
+}
+
+function timerRunIdempotencyKey(timer: ScheduledTimer, runNumber: number): string {
+  const base = timer.idempotencyKey ?? `scheduler:${timer.id}`;
+  return `${base}:run:${runNumber}`;
+}
+
+function persistedAuthContext(timer: ScheduledTimer): AuthContext {
+  const component: ComponentToken = {
+    sub: timer.createdBy,
+    role: timer.createdByKind,
+    scope: timer.createdByScopes,
+    constraints: timer.createdByConstraints,
+    iat: Math.floor(timer.createdAt / 1000),
+  };
+  return {
+    actor: { id: timer.createdBy, kind: "component" },
+    scopes: timer.createdByScopes,
+    constraints: timer.createdByConstraints,
+    callerAgentId: timer.deliveryFrom === "system" ? undefined : timer.deliveryFrom,
+    component,
+  };
+}
+
+function normalizeSchedule(input: ScheduleTimerInput, now: number): { kind: TimerScheduleKind; def: TimerScheduleDef; nextRunAt: number } {
+  if (input.rrule || input.timezone) throw new ValidationError("rrule/timezone timers are not supported yet");
+  const modes = [input.afterMs !== undefined, input.at !== undefined, input.everyMs !== undefined].filter(Boolean).length;
+  if (modes !== 1) throw new ValidationError("provide exactly one of afterMs, at, or everyMs");
+  if (input.afterMs !== undefined) {
+    const afterMs = cleanPositiveInt(input.afterMs, "afterMs")!;
+    return { kind: "once", def: { afterMs }, nextRunAt: now + afterMs };
+  }
+  if (input.at !== undefined) {
+    const atMs = Date.parse(input.at);
+    if (!Number.isFinite(atMs) || atMs <= now) throw new ValidationError("at must be a future ISO timestamp");
+    return { kind: "once", def: { at: new Date(atMs).toISOString() }, nextRunAt: atMs };
+  }
+  const everyMs = cleanPositiveInt(input.everyMs, "everyMs")!;
+  return { kind: "interval", def: { everyMs }, nextRunAt: now + everyMs };
+}
+
+function normalizeTarget(target: string | undefined, ctx: AuthContext): string {
+  const raw = cleanOptionalString(target, "target", 200) ?? "me";
+  if (raw !== "me") return raw;
+  if (!ctx.callerAgentId) throw new ValidationError("target defaults to me, but caller has no single agent identity");
+  return ctx.callerAgentId;
+}
+
+function cleanBody(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError("body required");
+  const body = value.trim();
+  if (new TextEncoder().encode(body).byteLength > MAX_BODY_BYTES) throw new ValidationError(`body exceeds ${MAX_BODY_BYTES} bytes`);
+  return body;
+}
+
+function cleanPayload(value: unknown): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ValidationError("payload must be an object");
+  const payload = value as Record<string, unknown>;
+  if (new TextEncoder().encode(JSON.stringify(payload)).byteLength > SCHEDULER_MAX_PAYLOAD_BYTES) {
+    throw new ValidationError(`payload exceeds ${SCHEDULER_MAX_PAYLOAD_BYTES} bytes`);
+  }
+  return payload;
+}
+
+function cleanOptionalString(value: unknown, field: string, max: number): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return trimmed;
+}
+
+function cleanPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}
+
+function cleanExpiresAt(value: unknown, now: number): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const ms = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : NaN;
+  if (!Number.isFinite(ms) || ms <= now) throw new ValidationError("expiresAt must be a future ISO timestamp or unix timestamp in milliseconds");
+  return ms;
+}
+
+function canAdministerTimers(ctx: AuthContext): boolean {
+  return ctx.actor.kind === "system" || hasScope(ctx.scopes, "system:admin");
+}
+
+function canCreatePersistentTimer(ctx: AuthContext): boolean {
+  return canAdministerTimers(ctx) || hasScope(ctx.scopes, "schedule:persistent");
+}