agent-relay-server 0.88.3 → 0.89.0

package/src/db/migrations.ts

@@ -881,4 +881,40 @@ export function applyMigrations(): void {
   getDb().run("DROP INDEX IF EXISTS idx_terminal_events_agent");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_terminal_events_agent ON terminal_events(agent_id, epoch, created_at DESC)");
 
+  // #361 — persistent Relay scheduler. Keep this append-only at the end: older DBs may
+  // have reached this point through many schema vintages, and the table references messages.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS scheduled_timers (
+      id TEXT PRIMARY KEY,
+      target TEXT NOT NULL,
+      created_by TEXT NOT NULL,
+      created_by_kind TEXT NOT NULL,
+      created_by_scopes TEXT NOT NULL DEFAULT '[]',
+      created_by_constraints TEXT,
+      delivery_from TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      next_run_at INTEGER NOT NULL,
+      schedule_kind TEXT NOT NULL,
+      schedule_def TEXT NOT NULL,
+      subject TEXT,
+      body TEXT NOT NULL,
+      payload TEXT NOT NULL DEFAULT '{}',
+      enabled INTEGER NOT NULL DEFAULT 1,
+      run_count INTEGER NOT NULL DEFAULT 0,
+      max_runs INTEGER,
+      expires_at INTEGER,
+      last_run_at INTEGER,
+      last_error TEXT,
+      consecutive_failures INTEGER NOT NULL DEFAULT 0,
+      idempotency_key TEXT,
+      correlation_id TEXT NOT NULL,
+      last_message_id INTEGER REFERENCES messages(id),
+      claimed_by TEXT,
+      claim_expires_at INTEGER
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_due ON scheduled_timers(enabled, next_run_at, claim_expires_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_creator ON scheduled_timers(created_by, enabled, next_run_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_correlation ON scheduled_timers(correlation_id)");
+
 }

package/src/db/scheduled-timers.ts

@@ -0,0 +1,297 @@
+import { randomUUID } from "node:crypto";
+import { getDb } from "./connection.ts";
+import type { TokenConstraints } from "../types";
+
+export type TimerScheduleKind = "once" | "interval";
+
+export interface TimerScheduleDef {
+  afterMs?: number;
+  at?: string;
+  everyMs?: number;
+}
+
+export interface ScheduledTimer {
+  id: string;
+  target: string;
+  createdBy: string;
+  createdByKind: string;
+  createdByScopes: string[];
+  createdByConstraints?: TokenConstraints;
+  deliveryFrom: string;
+  createdAt: number;
+  nextRunAt: number;
+  scheduleKind: TimerScheduleKind;
+  scheduleDef: TimerScheduleDef;
+  subject?: string;
+  body: string;
+  payload: Record<string, unknown>;
+  enabled: boolean;
+  runCount: number;
+  maxRuns?: number;
+  expiresAt?: number;
+  lastRunAt?: number;
+  lastError?: string;
+  consecutiveFailures: number;
+  idempotencyKey?: string;
+  correlationId: string;
+  lastMessageId?: number;
+  claimedBy?: string;
+  claimExpiresAt?: number;
+}
+
+interface ScheduledTimerRow {
+  id: string;
+  target: string;
+  created_by: string;
+  created_by_kind: string;
+  created_by_scopes: string;
+  created_by_constraints: string | null;
+  delivery_from: string;
+  created_at: number;
+  next_run_at: number;
+  schedule_kind: string;
+  schedule_def: string;
+  subject: string | null;
+  body: string;
+  payload: string;
+  enabled: number;
+  run_count: number;
+  max_runs: number | null;
+  expires_at: number | null;
+  last_run_at: number | null;
+  last_error: string | null;
+  consecutive_failures: number;
+  idempotency_key: string | null;
+  correlation_id: string;
+  last_message_id: number | null;
+  claimed_by: string | null;
+  claim_expires_at: number | null;
+}
+
+export interface CreateScheduledTimerRowInput {
+  target: string;
+  createdBy: string;
+  createdByKind: string;
+  createdByScopes: string[];
+  createdByConstraints?: TokenConstraints;
+  deliveryFrom: string;
+  nextRunAt: number;
+  scheduleKind: TimerScheduleKind;
+  scheduleDef: TimerScheduleDef;
+  subject?: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  maxRuns?: number;
+  expiresAt?: number;
+  idempotencyKey?: string;
+}
+
+export function insertScheduledTimer(input: CreateScheduledTimerRowInput, now = Date.now()): ScheduledTimer {
+  const id = randomUUID();
+  const correlationId = `timer:${id}`;
+  getDb().query(`
+    INSERT INTO scheduled_timers (
+      id, target, created_by, created_by_kind, created_by_scopes, created_by_constraints, delivery_from,
+      created_at, next_run_at, schedule_kind, schedule_def, subject, body, payload, enabled,
+      run_count, max_runs, expires_at, idempotency_key, correlation_id
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 0, ?, ?, ?, ?)
+  `).run(
+    id,
+    input.target,
+    input.createdBy,
+    input.createdByKind,
+    JSON.stringify(input.createdByScopes),
+    input.createdByConstraints ? JSON.stringify(input.createdByConstraints) : null,
+    input.deliveryFrom,
+    now,
+    input.nextRunAt,
+    input.scheduleKind,
+    JSON.stringify(input.scheduleDef),
+    input.subject ?? null,
+    input.body,
+    JSON.stringify(input.payload ?? {}),
+    input.maxRuns ?? null,
+    input.expiresAt ?? null,
+    input.idempotencyKey ?? null,
+    correlationId,
+  );
+  return getScheduledTimer(id)!;
+}
+
+export function getScheduledTimer(id: string): ScheduledTimer | null {
+  const row = getDb().query("SELECT * FROM scheduled_timers WHERE id = ?").get(id) as ScheduledTimerRow | undefined;
+  return row ? rowToTimer(row) : null;
+}
+
+export function listScheduledTimers(input: {
+  createdBy?: string;
+  includeDisabled?: boolean;
+  limit?: number;
+} = {}): ScheduledTimer[] {
+  const where: string[] = [];
+  const params: Array<string | number> = [];
+  if (input.createdBy) {
+    where.push("created_by = ?");
+    params.push(input.createdBy);
+  }
+  if (!input.includeDisabled) where.push("enabled = 1");
+  const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+  const sql = `SELECT * FROM scheduled_timers${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY next_run_at ASC, created_at ASC LIMIT ?`;
+  const rows = getDb().query(sql).all(...params, limit) as ScheduledTimerRow[];
+  return rows.map(rowToTimer);
+}
+
+export function countActiveScheduledTimers(createdBy: string): number {
+  const row = getDb()
+    .query("SELECT count(*) AS count FROM scheduled_timers WHERE created_by = ? AND enabled = 1")
+    .get(createdBy) as { count: number };
+  return row.count;
+}
+
+export function listDueScheduledTimerIds(now: number, limit = 25): string[] {
+  const rows = getDb().query(`
+    SELECT id FROM scheduled_timers
+    WHERE enabled = 1
+      AND next_run_at <= ?
+      AND (claim_expires_at IS NULL OR claim_expires_at <= ?)
+    ORDER BY next_run_at ASC, created_at ASC
+    LIMIT ?
+  `).all(now, now, limit) as Array<{ id: string }>;
+  return rows.map((row) => row.id);
+}
+
+export function claimScheduledTimer(id: string, owner: string, now: number, leaseMs: number): ScheduledTimer | null {
+  const claimExpiresAt = now + leaseMs;
+  const result = getDb().query(`
+    UPDATE scheduled_timers
+    SET claimed_by = ?, claim_expires_at = ?
+    WHERE id = ?
+      AND enabled = 1
+      AND next_run_at <= ?
+      AND (claim_expires_at IS NULL OR claim_expires_at <= ?)
+  `).run(owner, claimExpiresAt, id, now, now);
+  return result.changes === 0 ? null : getScheduledTimer(id);
+}
+
+export function completeScheduledTimerRun(input: {
+  timer: ScheduledTimer;
+  messageId: number;
+  now: number;
+}): ScheduledTimer {
+  const runCount = input.timer.runCount + 1;
+  const everyMs = input.timer.scheduleKind === "interval" ? input.timer.scheduleDef.everyMs : undefined;
+  const candidateNextRunAt = everyMs ? Math.max(input.now + everyMs, input.timer.nextRunAt + everyMs) : null;
+  const reachedMaxRuns = input.timer.maxRuns !== undefined && runCount >= input.timer.maxRuns;
+  const expiredBeforeNext = input.timer.expiresAt !== undefined &&
+    (candidateNextRunAt === null || candidateNextRunAt > input.timer.expiresAt);
+  const enabled = Boolean(candidateNextRunAt && !reachedMaxRuns && !expiredBeforeNext);
+
+  getDb().query(`
+    UPDATE scheduled_timers
+    SET run_count = ?,
+        last_run_at = ?,
+        last_error = NULL,
+        consecutive_failures = 0,
+        last_message_id = ?,
+        next_run_at = COALESCE(?, next_run_at),
+        enabled = ?,
+        claimed_by = NULL,
+        claim_expires_at = NULL
+    WHERE id = ?
+  `).run(runCount, input.now, input.messageId, candidateNextRunAt, enabled ? 1 : 0, input.timer.id);
+  return getScheduledTimer(input.timer.id)!;
+}
+
+export function recordScheduledTimerFailure(input: {
+  id: string;
+  error: string;
+  now: number;
+  retryMs: number;
+  maxFailures: number;
+}): ScheduledTimer | null {
+  const current = getScheduledTimer(input.id);
+  if (!current) return null;
+  const failures = current.consecutiveFailures + 1;
+  const enabled = failures < input.maxFailures;
+  getDb().query(`
+    UPDATE scheduled_timers
+    SET last_error = ?,
+        consecutive_failures = ?,
+        next_run_at = ?,
+        enabled = ?,
+        claimed_by = NULL,
+        claim_expires_at = NULL
+    WHERE id = ?
+  `).run(input.error, failures, input.now + input.retryMs, enabled ? 1 : 0, input.id);
+  return getScheduledTimer(input.id);
+}
+
+export function cancelScheduledTimer(id: string, now = Date.now()): ScheduledTimer | null {
+  const result = getDb().query(`
+    UPDATE scheduled_timers
+    SET enabled = 0, claimed_by = NULL, claim_expires_at = NULL, last_error = COALESCE(last_error, 'cancelled')
+    WHERE id = ? AND enabled = 1
+  `).run(id);
+  if (result.changes === 0) return getScheduledTimer(id);
+  return getScheduledTimer(id);
+}
+
+export function disableScheduledTimer(id: string, reason: string): ScheduledTimer | null {
+  getDb().query(`
+    UPDATE scheduled_timers
+    SET enabled = 0, last_error = ?, claimed_by = NULL, claim_expires_at = NULL
+    WHERE id = ?
+  `).run(reason, id);
+  return getScheduledTimer(id);
+}
+
+function rowToTimer(row: ScheduledTimerRow): ScheduledTimer {
+  return {
+    id: row.id,
+    target: row.target,
+    createdBy: row.created_by,
+    createdByKind: row.created_by_kind,
+    createdByScopes: parseStringArray(row.created_by_scopes),
+    createdByConstraints: parseRecord(row.created_by_constraints) as TokenConstraints | undefined,
+    deliveryFrom: row.delivery_from,
+    createdAt: row.created_at,
+    nextRunAt: row.next_run_at,
+    scheduleKind: row.schedule_kind === "interval" ? "interval" : "once",
+    scheduleDef: parseRecord(row.schedule_def) as TimerScheduleDef,
+    subject: row.subject ?? undefined,
+    body: row.body,
+    payload: parseRecord(row.payload) ?? {},
+    enabled: row.enabled === 1,
+    runCount: row.run_count,
+    maxRuns: row.max_runs ?? undefined,
+    expiresAt: row.expires_at ?? undefined,
+    lastRunAt: row.last_run_at ?? undefined,
+    lastError: row.last_error ?? undefined,
+    consecutiveFailures: row.consecutive_failures,
+    idempotencyKey: row.idempotency_key ?? undefined,
+    correlationId: row.correlation_id,
+    lastMessageId: row.last_message_id ?? undefined,
+    claimedBy: row.claimed_by ?? undefined,
+    claimExpiresAt: row.claim_expires_at ?? undefined,
+  };
+}
+
+function parseRecord(raw: string | null): Record<string, unknown> | undefined {
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseStringArray(raw: string): string[] {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/src/db/schema.ts

@@ -164,6 +164,37 @@ export function initDb(path: string = "agent-relay.db"): Database {
     -- per candidate row (O(n^2)): ~8.6s at 4k rows, which blew the 5s Stop-hook
     -- timeout and wedged turns in "busy" (#199).
     CREATE INDEX IF NOT EXISTS idx_msg_reply_to ON messages(reply_to, from_agent);
+    CREATE TABLE IF NOT EXISTS scheduled_timers (
+      id TEXT PRIMARY KEY,
+      target TEXT NOT NULL,
+      created_by TEXT NOT NULL,
+      created_by_kind TEXT NOT NULL,
+      created_by_scopes TEXT NOT NULL DEFAULT '[]',
+      created_by_constraints TEXT,
+      delivery_from TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      next_run_at INTEGER NOT NULL,
+      schedule_kind TEXT NOT NULL,
+      schedule_def TEXT NOT NULL,
+      subject TEXT,
+      body TEXT NOT NULL,
+      payload TEXT NOT NULL DEFAULT '{}',
+      enabled INTEGER NOT NULL DEFAULT 1,
+      run_count INTEGER NOT NULL DEFAULT 0,
+      max_runs INTEGER,
+      expires_at INTEGER,
+      last_run_at INTEGER,
+      last_error TEXT,
+      consecutive_failures INTEGER NOT NULL DEFAULT 0,
+      idempotency_key TEXT,
+      correlation_id TEXT NOT NULL,
+      last_message_id INTEGER REFERENCES messages(id),
+      claimed_by TEXT,
+      claim_expires_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_scheduled_timers_due ON scheduled_timers(enabled, next_run_at, claim_expires_at);
+    CREATE INDEX IF NOT EXISTS idx_scheduled_timers_creator ON scheduled_timers(created_by, enabled, next_run_at);
+    CREATE INDEX IF NOT EXISTS idx_scheduled_timers_correlation ON scheduled_timers(correlation_id);
     CREATE TABLE IF NOT EXISTS teams (
       id TEXT PRIMARY KEY,
       coordinator_id TEXT,

package/src/index.ts

@@ -13,6 +13,7 @@ import { startConnectorStatusPoller } from "./connectors";
 import { installNotificationSubscriptionRule } from "./notification-subscription-rules";
 import { installQuotaAdvisoryHandler } from "./quota-advisory";
 import { startPlanLiveBindings } from "./services/plan-live-bindings";
+import { startRelayScheduler } from "./services/scheduler";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import {
@@ -85,6 +86,7 @@ function startServer(): void {
   reconcileRelayVersion();
   startConnectorStatusPoller();
   startMaintenanceScheduler();
+  startRelayScheduler();
 
   setInterval(() => {
     emitAutomationReconciliations(reconcileAutomationRuns());

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