vellum 0.2.1 → 0.2.2

package/src/runtime/http-server.ts

@@ -10,7 +10,6 @@ import { resolve } from 'node:path';
 import { timingSafeEqual } from 'node:crypto';
 import { ConfigError, IngressBlockedError } from '../util/errors.js';
 import { getLogger } from '../util/logger.js';
-import { getSecureKey } from '../security/secure-keys.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 
@@ -47,11 +46,16 @@ import {
   handleDeleteSharedApp,
 } from './routes/app-routes.js';
 import { handleAddSecret } from './routes/secret-routes.js';
+import {
+  handleStartCall,
+  handleGetCallStatus,
+  handleCancelCall,
+  handleAnswerCall,
+} from './routes/call-routes.js';
 import {
   handleVoiceWebhook,
   handleStatusCallback,
   handleConnectAction,
-  handleCallAnswer,
 } from '../calls/twilio-routes.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
@@ -113,25 +117,50 @@ function getDiskSpaceInfo(): DiskSpaceInfo | null {
  */
 const TWILIO_WEBHOOK_RE = /^\/v1\/(?:assistants\/[^/]+\/)?calls\/twilio\/(.+)$/;
 
+/**
+ * Gateway-compatible Twilio webhook paths:
+ *   /webhooks/twilio/<subpath>
+ *
+ * Maps gateway path segments to the internal subpath names used by the
+ * dispatcher below (e.g. "voice" -> "voice-webhook").
+ */
+const TWILIO_GATEWAY_WEBHOOK_RE = /^\/webhooks\/twilio\/(.+)$/;
+const GATEWAY_SUBPATH_MAP: Record<string, string> = {
+  voice: 'voice-webhook',
+  status: 'status',
+  'connect-action': 'connect-action',
+};
+
 /**
  * Validate a Twilio webhook request's X-Twilio-Signature header.
  *
  * Returns the raw body text on success so callers can reconstruct the Request
  * for downstream handlers (which also need to read the body).
  * Returns a 403 Response if signature validation fails.
- * If the Twilio auth token is not configured, skips validation with a warning.
+ *
+ * Fail-closed: if the auth token is not configured, the request is rejected
+ * with 403 rather than silently skipping validation. An explicit local-dev
+ * bypass is available via TWILIO_WEBHOOK_VALIDATION_DISABLED=true.
  */
 async function validateTwilioWebhook(
   req: Request,
 ): Promise<{ body: string } | Response> {
   const rawBody = await req.text();
-  const authToken = getSecureKey('twilio_auth_token');
 
-  if (!authToken) {
-    log.warn('Twilio auth token not configured — skipping webhook signature validation');
+  // Allow explicit local-dev bypass — must be exactly "true"
+  if (process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED === 'true') {
+    log.warn('Twilio webhook signature validation explicitly disabled via TWILIO_WEBHOOK_VALIDATION_DISABLED');
     return { body: rawBody };
   }
 
+  const authToken = TwilioConversationRelayProvider.getAuthToken();
+
+  // Fail-closed: reject if no auth token is configured
+  if (!authToken) {
+    log.error('Twilio auth token not configured — rejecting webhook request (fail-closed)');
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
   const signature = req.headers.get('x-twilio-signature');
   if (!signature) {
     log.warn('Twilio webhook request missing X-Twilio-Signature header');
@@ -159,6 +188,7 @@ async function validateTwilioWebhook(
     publicUrl,
     params,
     signature,
+    authToken,
   );
 
   if (!isValid) {
@@ -302,11 +332,18 @@ export class RuntimeHttpServer {
 
     // ── Twilio webhook endpoints — before auth check because Twilio
     //    webhook POSTs don't include bearer tokens.
-    //    Supports both /v1/calls/twilio/* and /v1/assistants/:id/calls/twilio/*
+    //    Supports /v1/calls/twilio/*, /v1/assistants/:id/calls/twilio/*,
+    //    and gateway-compatible /webhooks/twilio/* paths.
     //    Validates X-Twilio-Signature to prevent unauthorized access. ──
     const twilioMatch = path.match(TWILIO_WEBHOOK_RE);
-    if (twilioMatch && req.method === 'POST') {
-      const twilioSubpath = twilioMatch[1];
+    const gatewayTwilioMatch = !twilioMatch ? path.match(TWILIO_GATEWAY_WEBHOOK_RE) : null;
+    const resolvedTwilioSubpath = twilioMatch
+      ? twilioMatch[1]
+      : gatewayTwilioMatch
+        ? GATEWAY_SUBPATH_MAP[gatewayTwilioMatch[1]]
+        : null;
+    if (resolvedTwilioSubpath && req.method === 'POST') {
+      const twilioSubpath = resolvedTwilioSubpath;
 
       // Validate Twilio request signature before dispatching
       const validation = await validateTwilioWebhook(req);
@@ -335,17 +372,6 @@ export class RuntimeHttpServer {
       }
     }
 
-    // ── Call answer endpoint — behind auth gate ──────────────────────
-    const callAnswerMatch = path.match(/^\/v1\/calls\/([^/]+)\/answer$/);
-    if (callAnswerMatch && req.method === 'POST') {
-      try {
-        return await handleCallAnswer(req, callAnswerMatch[1]);
-      } catch (err) {
-        log.error({ err, callSessionId: callAnswerMatch[1] }, 'Runtime HTTP handler error answering call');
-        return Response.json({ error: 'Internal server error' }, { status: 500 });
-      }
-    }
-
     // Serve shareable app pages
     const pagesMatch = path.match(/^\/pages\/([^/]+)$/);
     if (pagesMatch && req.method === 'GET') {
@@ -529,6 +555,68 @@ export class RuntimeHttpServer {
         return await handleReplayDeadLetters(req);
       }
 
+      // ── Call API routes ───────────────────────────────────────────
+      if (endpoint === 'calls/start' && req.method === 'POST') {
+        return await handleStartCall(req);
+      }
+
+      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer
+      const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer)?$/);
+      if (callsMatch) {
+        const callSessionId = callsMatch[1];
+        // Skip known sub-paths that are handled elsewhere (twilio, relay)
+        if (callSessionId !== 'twilio' && callSessionId !== 'relay' && callSessionId !== 'start') {
+          if (callsMatch[2] === '/cancel' && req.method === 'POST') {
+            return await handleCancelCall(req, callSessionId);
+          }
+          if (callsMatch[2] === '/answer' && req.method === 'POST') {
+            return await handleAnswerCall(req, callSessionId);
+          }
+          if (!callsMatch[2] && req.method === 'GET') {
+            return handleGetCallStatus(callSessionId);
+          }
+        }
+      }
+
+      // ── Internal Twilio forwarding endpoints (gateway → runtime) ──
+      // These accept JSON payloads from the gateway (which already validated
+      // the Twilio signature) and reconstruct requests for the existing
+      // Twilio route handlers.
+      if (endpoint === 'internal/twilio/voice-webhook' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string>; originalUrl?: string };
+        const formBody = new URLSearchParams(json.params).toString();
+        // Reconstruct request URL: keep the original URL query string (callSessionId)
+        const reconstructedUrl = json.originalUrl ?? req.url;
+        const fakeReq = new Request(reconstructedUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: formBody,
+        });
+        return await handleVoiceWebhook(fakeReq);
+      }
+
+      if (endpoint === 'internal/twilio/status' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string> };
+        const formBody = new URLSearchParams(json.params).toString();
+        const fakeReq = new Request(req.url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: formBody,
+        });
+        return await handleStatusCallback(fakeReq);
+      }
+
+      if (endpoint === 'internal/twilio/connect-action' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string> };
+        const formBody = new URLSearchParams(json.params).toString();
+        const fakeReq = new Request(req.url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: formBody,
+        });
+        return await handleConnectAction(fakeReq);
+      }
+
       return Response.json({ error: 'Not found', source: 'runtime' }, { status: 404 });
     } catch (err) {
       if (err instanceof IngressBlockedError) {

package/src/runtime/routes/attachment-routes.ts

@@ -56,7 +56,6 @@ export async function handleUploadAttachment(req: Request): Promise<Response> {
   let attachment: attachmentsStore.StoredAttachment;
   try {
     attachment = attachmentsStore.uploadAttachment(
-      "self",
       filename,
       mimeType,
       data,
@@ -98,7 +97,7 @@ export async function handleDeleteAttachment(req: Request): Promise<Response> {
     );
   }
 
-  const result = attachmentsStore.deleteAttachment("self", attachmentId);
+  const result = attachmentsStore.deleteAttachment(attachmentId);
 
   if (result === 'not_found') {
     return Response.json(
@@ -118,7 +117,7 @@ export async function handleDeleteAttachment(req: Request): Promise<Response> {
 }
 
 export function handleGetAttachment(attachmentId: string): Response {
-  const attachment = attachmentsStore.getAttachmentById("self", attachmentId);
+  const attachment = attachmentsStore.getAttachmentById(attachmentId);
   if (!attachment) {
     return Response.json({ error: 'Attachment not found' }, { status: 404 });
   }

package/src/runtime/routes/call-routes.ts

@@ -0,0 +1,140 @@
+/**
+ * Runtime HTTP route handlers for the call API.
+ *
+ * POST   /v1/calls/start              — initiate a new call
+ * GET    /v1/calls/:callSessionId      — get call status
+ * POST   /v1/calls/:callSessionId/cancel — cancel a call
+ * POST   /v1/calls/:callSessionId/answer — answer a pending question
+ */
+
+import { startCall, getCallStatus, cancelCall, answerCall } from '../../calls/call-domain.js';
+import { getConfig } from '../../config/loader.js';
+
+/**
+ * POST /v1/calls/start
+ *
+ * Body: { phoneNumber: string; task: string; context?: string; conversationId: string }
+ */
+export async function handleStartCall(req: Request): Promise<Response> {
+  if (!getConfig().calls.enabled) {
+    return Response.json(
+      { error: 'Calls feature is disabled via configuration. Set calls.enabled to true to use this feature.' },
+      { status: 403 },
+    );
+  }
+
+  let body: {
+    phoneNumber?: string;
+    task?: string;
+    context?: string;
+    conversationId?: string;
+  };
+  try {
+    body = await req.json() as typeof body;
+  } catch {
+    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+
+  if (!body.conversationId) {
+    return Response.json({ error: 'conversationId is required' }, { status: 400 });
+  }
+
+  const result = await startCall({
+    phoneNumber: body.phoneNumber ?? '',
+    task: body.task ?? '',
+    context: body.context,
+    conversationId: body.conversationId,
+  });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({
+    callSessionId: result.session.id,
+    callSid: result.callSid,
+    status: result.session.status,
+    toNumber: result.session.toNumber,
+    fromNumber: result.session.fromNumber,
+  }, { status: 201 });
+}
+
+/**
+ * GET /v1/calls/:callSessionId
+ */
+export function handleGetCallStatus(callSessionId: string): Response {
+  const result = getCallStatus(callSessionId);
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  const { session } = result;
+  return Response.json({
+    callSessionId: session.id,
+    conversationId: session.conversationId,
+    status: session.status,
+    toNumber: session.toNumber,
+    fromNumber: session.fromNumber,
+    provider: session.provider,
+    providerCallSid: session.providerCallSid,
+    task: session.task,
+    startedAt: session.startedAt ? new Date(session.startedAt).toISOString() : null,
+    endedAt: session.endedAt ? new Date(session.endedAt).toISOString() : null,
+    lastError: session.lastError,
+    pendingQuestion: result.pendingQuestion ?? null,
+    createdAt: new Date(session.createdAt).toISOString(),
+    updatedAt: new Date(session.updatedAt).toISOString(),
+  });
+}
+
+/**
+ * POST /v1/calls/:callSessionId/cancel
+ *
+ * Body: { reason?: string }
+ */
+export async function handleCancelCall(req: Request, callSessionId: string): Promise<Response> {
+  let reason: string | undefined;
+  try {
+    const body = await req.json() as { reason?: string };
+    reason = body.reason;
+  } catch {
+    // Empty body is fine
+  }
+
+  const result = await cancelCall({ callSessionId, reason });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({
+    callSessionId: result.session.id,
+    status: result.session.status,
+  });
+}
+
+/**
+ * POST /v1/calls/:callSessionId/answer
+ *
+ * Body: { answer: string }
+ */
+export async function handleAnswerCall(req: Request, callSessionId: string): Promise<Response> {
+  let body: { answer?: string };
+  try {
+    body = await req.json() as typeof body;
+  } catch {
+    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+
+  const result = await answerCall({
+    callSessionId,
+    answer: body.answer ?? '',
+  });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({ ok: true, questionId: result.questionId });
+}

package/src/runtime/routes/channel-routes.ts

@@ -34,7 +34,7 @@ export async function handleDeleteConversation(req: Request): Promise<Response>
   }
 
   const conversationKey = `${sourceChannel}:${externalChatId}`;
-  deleteConversationKey("self", conversationKey);
+  deleteConversationKey(conversationKey);
 
   return Response.json({ ok: true });
 }
@@ -89,7 +89,7 @@ export async function handleChannelInbound(
   }
 
   if (hasAttachments) {
-    const resolved = attachmentsStore.getAttachmentsByIds("self", attachmentIds);
+    const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
@@ -112,7 +112,6 @@ export async function handleChannelInbound(
   if (isEdit && sourceMessageId) {
     // Dedup the edit event itself (retried edited_message webhooks)
     const editResult = channelDeliveryStore.recordInbound(
-      "self",
       sourceChannel,
       externalChatId,
       externalMessageId,
@@ -136,7 +135,6 @@ export async function handleChannelInbound(
     let original: { messageId: string; conversationId: string } | null = null;
     for (let attempt = 0; attempt <= EDIT_LOOKUP_RETRIES; attempt++) {
       original = channelDeliveryStore.findMessageBySourceId(
-        "self",
         sourceChannel,
         externalChatId,
         sourceMessageId,
@@ -173,7 +171,6 @@ export async function handleChannelInbound(
 
   // ── New message path ──
   const result = channelDeliveryStore.recordInbound(
-    "self",
     sourceChannel,
     externalChatId,
     externalMessageId,
@@ -239,7 +236,6 @@ export async function handleChannelInbound(
     } catch (err) {
       // Secret ingress blocks are not retryable — let the top-level handler return 422
       if (err instanceof IngressBlockedError) throw err;
-      console.error(`[runtime-http] Processing failed`, err);
       log.error({ err, conversationId: result.conversationId }, 'Failed to process channel inbound message');
       channelDeliveryStore.recordProcessingFailure(result.eventId, err);
     }
@@ -257,7 +253,7 @@ export async function handleChannelInbound(
         try { parsed = JSON.parse(msgs[i].content); } catch { parsed = msgs[i].content; }
         const rendered = renderHistoryContent(parsed);
 
-        const linked = attachmentsStore.getAttachmentMetadataForMessage(msgs[i].id, "self");
+        const linked = attachmentsStore.getAttachmentMetadataForMessage(msgs[i].id);
         const replyAttachments: RuntimeAttachmentMetadata[] = linked.map((a) => ({
           id: a.id,
           filename: a.originalFilename,
@@ -290,7 +286,7 @@ export async function handleChannelInbound(
 }
 
 export function handleListDeadLetters(): Response {
-  const events = channelDeliveryStore.getDeadLetterEvents("self");
+  const events = channelDeliveryStore.getDeadLetterEvents();
   return Response.json({ events });
 }
 
@@ -302,7 +298,7 @@ export async function handleReplayDeadLetters(req: Request): Promise<Response> {
     return Response.json({ error: 'eventIds array is required' }, { status: 400 });
   }
 
-  const replayed = channelDeliveryStore.replayDeadLetters("self", eventIds);
+  const replayed = channelDeliveryStore.replayDeadLetters(eventIds);
   return Response.json({ replayed });
 }
 
@@ -326,7 +322,6 @@ export async function handleChannelDeliveryAck(req: Request): Promise<Response>
   }
 
   const acked = channelDeliveryStore.acknowledgeDelivery(
-    "self",
     sourceChannel,
     externalChatId,
     externalMessageId,

package/src/runtime/routes/conversation-routes.ts

@@ -54,7 +54,7 @@ export function handleListMessages(
     );
   }
 
-  const mapping = getConversationByKey("self", conversationKey);
+  const mapping = getConversationByKey(conversationKey);
   if (!mapping) {
     return Response.json({ messages: [] });
   }
@@ -89,7 +89,7 @@ export function handleListMessages(
   const messages: RuntimeMessagePayload[] = merged.map((m) => {
     let msgAttachments: RuntimeAttachmentMetadata[] = [];
     if (m.role === 'assistant' && m.id) {
-      const linked = attachmentsStore.getAttachmentMetadataForMessage(m.id, "self");
+      const linked = attachmentsStore.getAttachmentMetadataForMessage(m.id);
       if (linked.length > 0) {
         msgAttachments = linked.map((a) => ({
           id: a.id,
@@ -170,7 +170,7 @@ export async function handleSendMessage(
 
   // Validate that all attachment IDs resolve
   if (hasAttachments) {
-    const resolved = attachmentsStore.getAttachmentsByIds("self", attachmentIds);
+    const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
@@ -181,7 +181,7 @@ export async function handleSendMessage(
     }
   }
 
-  const mapping = getOrCreateConversation("self", conversationKey);
+  const mapping = getOrCreateConversation(conversationKey);
 
   const processor = deps.persistAndProcessMessage ?? deps.processMessage;
   if (!processor) {
@@ -247,7 +247,7 @@ export async function handleGetSuggestion(
     );
   }
 
-  const mapping = getConversationByKey("self", conversationKey);
+  const mapping = getConversationByKey(conversationKey);
   if (!mapping) {
     return Response.json({ suggestion: null, messageId: null, source: 'none' as const });
   }

package/src/runtime/routes/run-routes.ts

@@ -38,7 +38,7 @@ export async function handleCreateRun(
   }
 
   if (hasAttachments) {
-    const resolved = attachmentsStore.getAttachmentsByIds("self", attachmentIds);
+    const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
@@ -49,7 +49,7 @@ export async function handleCreateRun(
     }
   }
 
-  const mapping = getOrCreateConversation("self", conversationKey);
+  const mapping = getOrCreateConversation(conversationKey);
 
   try {
     const run = await runOrchestrator.startRun(

package/src/runtime/run-orchestrator.ts

@@ -14,6 +14,7 @@ import * as runsStore from '../memory/runs-store.js';
 import type { Run } from '../memory/runs-store.js';
 import type { Session } from '../daemon/session.js';
 import type { ServerMessage } from '../daemon/ipc-protocol.js';
+import { resolveChannelCapabilities } from '../daemon/session-runtime-assembly.js';
 import type { UserDecision } from '../permissions/types.js';
 import { checkIngressForSecrets } from '../security/secret-ingress.js';
 import { IngressBlockedError } from '../util/errors.js';
@@ -88,10 +89,11 @@ export class RunOrchestrator {
 
     const requestId = crypto.randomUUID();
     const messageId = session.persistUserMessage(content, attachments, requestId);
-    const run = runsStore.createRun('self', conversationId, messageId);
+    const run = runsStore.createRun(conversationId, messageId);
 
-    // Set the assistant ID so attachments are scoped correctly.
-    session.setAssistantId('self');
+    // Runs are always HTTP-originated; set channel capabilities so the attachment
+    // scope heuristic resolves to 'self' rather than 'local-assistant'.
+    session.setChannelCapabilities(resolveChannelCapabilities('http-api'));
 
     // Serialized publish chain so hub subscribers observe events in order.
     let hubChain: Promise<void> = Promise.resolve();
@@ -110,6 +112,7 @@ export class RunOrchestrator {
         });
     };
 
+
     // Hook into session to intercept confirmation_request events.
     // When the prompter sends a confirmation_request, we record it in the
     // run store so the web UI can poll and submit a decision.
@@ -144,6 +147,9 @@ export class RunOrchestrator {
     // Fire-and-forget the agent loop
     const cleanup = () => {
       this.pending.delete(run.id);
+      // Reset channel capabilities so a subsequent IPC/desktop session on the
+      // same conversation is not incorrectly treated as an HTTP-API client.
+      session.setChannelCapabilities(null);
       // Reset the session's client callback to a no-op so the stale
       // closure doesn't intercept events from future runs on the same session.
       // Set hasNoClient=true here since the run is done and no HTTP caller

package/src/schedule/recurrence-engine.ts

@@ -0,0 +1,138 @@
+import { Cron } from 'croner';
+import { rrulestr, RRuleSet } from 'rrule';
+import type { ScheduleSyntax } from './recurrence-types.js';
+
+export interface ScheduleSpec {
+  syntax: ScheduleSyntax;
+  expression: string;
+  timezone?: string | null;
+}
+
+const SUPPORTED_RRULE_PREFIXES = ['DTSTART', 'RRULE:', 'RDATE', 'EXDATE', 'EXRULE'];
+
+function normalizeRruleExpression(expression: string): string {
+  // Handle escaped newlines from JSON transport
+  return expression.replace(/\\n/g, '\n').trim();
+}
+
+function parseRruleLines(expression: string): string[] {
+  return normalizeRruleExpression(expression)
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(Boolean);
+}
+
+function validateRruleLines(lines: string[]): string | null {
+  let hasInclusion = false;
+  let hasDtstart = false;
+
+  for (const line of lines) {
+    const upper = line.toUpperCase();
+    if (!SUPPORTED_RRULE_PREFIXES.some(p => upper.startsWith(p))) {
+      return `Unsupported recurrence line: ${line}`;
+    }
+    if (upper.startsWith('DTSTART')) hasDtstart = true;
+    if (upper.startsWith('RRULE:') || upper.startsWith('RDATE')) hasInclusion = true;
+  }
+
+  if (!hasDtstart) return 'RRULE expression must include DTSTART for deterministic scheduling';
+  if (!hasInclusion) return 'RRULE expression must include at least one RRULE or RDATE';
+  return null;
+}
+
+/**
+ * Detect whether an RRULE expression contains set constructs (RDATE, EXDATE,
+ * EXRULE, or multiple RRULE lines) that require RRuleSet parsing.
+ */
+export function hasSetConstructs(expression: string): boolean {
+  const lines = parseRruleLines(expression);
+  let rruleCount = 0;
+  for (const line of lines) {
+    const upper = line.toUpperCase();
+    if (upper.startsWith('RDATE') || upper.startsWith('EXDATE') || upper.startsWith('EXRULE')) return true;
+    if (upper.startsWith('RRULE:')) rruleCount++;
+  }
+  return rruleCount > 1;
+}
+
+/**
+ * Validate RRULE set lines in an expression. Returns null if valid, or an
+ * actionable error string describing the problem. This is intended for tool
+ * layers that want to surface a specific error message before calling the
+ * store.
+ */
+export function validateRruleSetLines(expression: string): string | null {
+  const lines = parseRruleLines(expression);
+  return validateRruleLines(lines);
+}
+
+/**
+ * Validate a schedule expression. Returns true if the expression is valid
+ * for the given syntax, false otherwise.
+ */
+export function isValidScheduleExpression(spec: ScheduleSpec): boolean {
+  try {
+    if (spec.syntax === 'cron') {
+      new Cron(spec.expression, { maxRuns: 0 });
+      return true;
+    }
+
+    if (spec.syntax === 'rrule') {
+      const lines = parseRruleLines(spec.expression);
+      const error = validateRruleLines(lines);
+      if (error) return false;
+
+      const normalized = normalizeRruleExpression(spec.expression);
+      const tzid = spec.timezone ?? undefined;
+      if (hasSetConstructs(normalized)) {
+        rrulestr(normalized, { forceset: true, tzid });
+      } else {
+        rrulestr(normalized, { tzid });
+      }
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compute the next run timestamp (epoch ms) for a schedule expression.
+ * Throws if no future runs exist.
+ */
+export function computeNextRunAt(spec: ScheduleSpec, nowMs?: number): number {
+  const now = nowMs ?? Date.now();
+
+  if (spec.syntax === 'cron') {
+    const cron = new Cron(spec.expression, {
+      timezone: spec.timezone ?? undefined,
+    });
+    const next = cron.nextRun(new Date(now));
+    if (!next) {
+      throw new Error(`Cron expression "${spec.expression}" has no upcoming runs`);
+    }
+    return next.getTime();
+  }
+
+  if (spec.syntax === 'rrule') {
+    const normalized = normalizeRruleExpression(spec.expression);
+    const lines = parseRruleLines(normalized);
+    const error = validateRruleLines(lines);
+    if (error) throw new Error(error);
+
+    const useSet = hasSetConstructs(normalized);
+    const tzid = spec.timezone ?? undefined;
+    const parsed = useSet
+      ? (rrulestr(normalized, { forceset: true, tzid }) as RRuleSet)
+      : rrulestr(normalized, { tzid });
+    const next = parsed.after(new Date(now));
+    if (!next) {
+      throw new Error(`RRULE expression has no upcoming runs after ${new Date(now).toISOString()}`);
+    }
+    return next.getTime();
+  }
+
+  throw new Error(`Unsupported schedule syntax: ${spec.syntax}`);
+}