agent-relay-server 0.88.3 → 0.89.0

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

package/src/services/send-message.ts

@@ -53,6 +53,24 @@ interface SendMessageOptions {
   integration?: IntegrationTokenConfig | null;
 }
 
+export function validateSendMessageAuthorization(
+  input: SendMessageInput,
+  ctx: AuthContext,
+  opts: SendMessageOptions = {},
+): DeliveryReceipt {
+  applyReplyRouting(input);
+  if (!input.to) throw new ValidationError("to is required (or provide replyTo to auto-route)");
+  // De-singletoned human addressing (#393): collapse a human address to its stored/canonical
+  // form so `user:default` is a fully WORKING alias of the legacy bare `'user'` sink.
+  if (isHumanAgentId(input.to)) input.to = canonicalHumanAgentId(input.to);
+  if (input.from && isHumanAgentId(input.from)) input.from = canonicalHumanAgentId(input.from);
+  const reservedSink = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
+  input.from = resolveFrom(input, ctx, reservedSink);
+  const receipt = resolveSendTarget(input, input.from);
+  authorizeSend(input, ctx, opts, reservedSink);
+  return receipt;
+}
+
 /** `from` resolves from the token identity: `callerAgentId` (the resolved agent behind the
  * token) cannot be spoofed and WINS over any wire `from`. The wire value is a fallback only
  * for identity-less tokens (admin/server/integration/multi-agent).
@@ -157,22 +175,7 @@ export function sendMessageService(
   ctx: AuthContext,
   opts: SendMessageOptions = {},
 ): SendMessageResult {
-  applyReplyRouting(input);
-  if (!input.to) throw new ValidationError("to is required (or provide replyTo to auto-route)");
-  // De-singletoned human addressing (#393): collapse a human address to its stored/canonical
-  // form so `user:default` is a fully WORKING alias of the legacy bare `'user'` sink — it routes
-  // to the same agent row + inbox + thread, with zero live-byte movement. Per-user `user:<id>`
-  // addresses pass through unchanged for the later #388 waves; non-human ids are untouched.
-  if (isHumanAgentId(input.to)) input.to = canonicalHumanAgentId(input.to);
-  if (input.from && isHumanAgentId(input.from)) input.from = canonicalHumanAgentId(input.from);
-  // The reserved-sink observability lane (#284) governs both `from` resolution (wire `from` is
-  // authoritative — the runner reports an agent's turn) and authorization (drop the recipient
-  // predicate). Compute once, after reply-routing has settled `to`.
-  const reservedSink = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
-  input.from = resolveFrom(input, ctx, reservedSink);
-  // Resolve BEFORE authorize so both run against the canonical id (kills the HTTP-authorizes-raw
-  // vs MCP-authorizes-resolved drift).
-  const receipt = resolveSendTarget(input, input.from);
+  const receipt = validateSendMessageAuthorization(input, ctx, opts);
   // Reply-obligation linking: some real answers are ordinary sends without replyTo/thread linkage.
   // Channel bridge replies and spawn report-backs both have a single unambiguous open obligation case;
   // link those at send time so the obligation clears with one message and the Stop hook does not nag
@@ -182,8 +185,6 @@ export function sendMessageService(
       ?? spawnObligationAnsweredBy(input.from, input.to);
     if (answered !== null) input.replyTo = answered;
   }
-  authorizeSend(input, ctx, opts, reservedSink);
-
   const result = sendMessageWithResult(input);
   if (result.created) {
     if (result.message.deliveryStatus === "queued") {

package/src/token-db.ts

@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -88,7 +88,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -99,7 +99,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,
@@ -120,7 +120,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "MCP Client",
     description: "Tool-client access for Relay MCP calls plus message read/send.",
     role: "mcp",
-    scope: ["mcp:use", "message:read", "message:send"],
+    scope: ["mcp:use", "message:read", "message:send", "schedule:write"],
     ttlSeconds: 7 * 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -343,7 +343,7 @@ function ensureBuiltInTokenProfiles(): void {
 }
 
 function defaultScopes(role: string): string[] {
-  if (role === "provider") return ["agent:read", "agent:write", "message:send", "message:read", "artifact:read"];
+  if (role === "provider") return ["agent:read", "agent:write", "message:send", "message:read", "schedule:write", "artifact:read"];
   if (role === "channel") return ["agent:read", "agent:write", "message:send", "message:read"];
   if (role === "orchestrator") return ["agent:read", "agent:write", "command:*", "task:read", "task:write"];
   if (role === "admin" || role === "dashboard") return ["admin:*"];