vellum 0.2.1 → 0.2.7

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

@@ -10,10 +10,10 @@ import { renderHistoryContent } from '../../daemon/handlers.js';
 import { checkIngressForSecrets } from '../../security/secret-ingress.js';
 import { IngressBlockedError } from '../../util/errors.js';
 import { getLogger } from '../../util/logger.js';
+import { deliverChannelReply } from '../gateway-client.js';
 import type {
   MessageProcessor,
   RuntimeAttachmentMetadata,
-  RuntimeMessagePayload,
 } from '../http-types.js';
 
 const log = getLogger('runtime-http');
@@ -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 });
 }
@@ -54,6 +54,7 @@ export async function handleChannelInbound(
     senderExternalUserId?: string;
     senderUsername?: string;
     sourceMetadata?: Record<string, unknown>;
+    replyCallbackUrl?: string;
   };
 
   const {
@@ -89,7 +90,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 +113,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 +136,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 +172,6 @@ export async function handleChannelInbound(
 
   // ── New message path ──
   const result = channelDeliveryStore.recordInbound(
-    "self",
     sourceChannel,
     externalChatId,
     externalMessageId,
@@ -188,41 +186,92 @@ export async function handleChannelInbound(
     ? sourceMetadata.uxBrief.trim()
     : undefined;
 
-  // For new (non-duplicate) messages, run the agent loop to generate a reply.
-  let processingSucceeded = false;
+  const replyCallbackUrl = body.replyCallbackUrl;
+
+  // For new (non-duplicate) messages, run the secret ingress check
+  // synchronously, then fire off the agent loop in the background.
   if (!result.duplicate && processMessage) {
+    // Persist the raw payload first so dead-lettered events can always be
+    // replayed. If the ingress check later detects secrets we clear it
+    // before throwing, so secret-bearing content is never left on disk.
+    channelDeliveryStore.storePayload(result.eventId, {
+      sourceChannel, externalChatId, externalMessageId, content,
+      attachmentIds, sourceMetadata: body.sourceMetadata,
+      senderName: body.senderName,
+      senderExternalUserId: body.senderExternalUserId,
+      senderUsername: body.senderUsername,
+      replyCallbackUrl,
+    });
+
+    const contentToCheck = content ?? '';
+    let ingressCheck: ReturnType<typeof checkIngressForSecrets>;
     try {
-      // Persist the raw payload first so dead-lettered events can always be
-      // replayed. If the ingress check later detects secrets we clear it
-      // before throwing, so secret-bearing content is never left on disk.
-      channelDeliveryStore.storePayload(result.eventId, {
-        sourceChannel, externalChatId, externalMessageId, content,
-        attachmentIds, sourceMetadata: body.sourceMetadata,
-        senderName: body.senderName,
-        senderExternalUserId: body.senderExternalUserId,
-        senderUsername: body.senderUsername,
-      });
+      ingressCheck = checkIngressForSecrets(contentToCheck);
+    } catch (checkErr) {
+      channelDeliveryStore.clearPayload(result.eventId);
+      throw checkErr;
+    }
+    if (ingressCheck.blocked) {
+      channelDeliveryStore.clearPayload(result.eventId);
+      throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
+    }
 
-      const contentToCheck = content ?? '';
-      let ingressCheck: ReturnType<typeof checkIngressForSecrets>;
-      try {
-        ingressCheck = checkIngressForSecrets(contentToCheck);
-      } catch (checkErr) {
-        // If the secret check itself throws (e.g. ConfigError from corrupt
-        // config), clear the stored payload so secret-bearing content is
-        // never left on disk.
-        channelDeliveryStore.clearPayload(result.eventId);
-        throw checkErr;
-      }
-      if (ingressCheck.blocked) {
-        channelDeliveryStore.clearPayload(result.eventId);
-        throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
-      }
+    // Fire-and-forget: process the message and deliver the reply in the background.
+    // The HTTP response returns immediately so the gateway webhook is not blocked.
+    processChannelMessageInBackground({
+      processMessage,
+      conversationId: result.conversationId,
+      eventId: result.eventId,
+      content: content ?? '',
+      attachmentIds: hasAttachments ? attachmentIds : undefined,
+      sourceChannel,
+      externalChatId,
+      metadataHints,
+      metadataUxBrief,
+      replyCallbackUrl,
+    });
+  }
+
+  return Response.json({
+    accepted: result.accepted,
+    duplicate: result.duplicate,
+    eventId: result.eventId,
+  });
+}
 
+interface BackgroundProcessingParams {
+  processMessage: MessageProcessor;
+  conversationId: string;
+  eventId: string;
+  content: string;
+  attachmentIds?: string[];
+  sourceChannel: string;
+  externalChatId: string;
+  metadataHints: string[];
+  metadataUxBrief?: string;
+  replyCallbackUrl?: string;
+}
+
+function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
+  const {
+    processMessage,
+    conversationId,
+    eventId,
+    content,
+    attachmentIds,
+    sourceChannel,
+    externalChatId,
+    metadataHints,
+    metadataUxBrief,
+    replyCallbackUrl,
+  } = params;
+
+  (async () => {
+    try {
       const { messageId: userMessageId } = await processMessage(
-        result.conversationId,
-        content ?? '',
-        hasAttachments ? attachmentIds : undefined,
+        conversationId,
+        content,
+        attachmentIds,
         {
           transport: {
             channelId: sourceChannel,
@@ -232,65 +281,54 @@ export async function handleChannelInbound(
         },
         sourceChannel,
       );
-      // Link the user message to the inbound event so edits can find it later
-      channelDeliveryStore.linkMessage(result.eventId, userMessageId);
-      channelDeliveryStore.markProcessed(result.eventId);
-      processingSucceeded = true;
+      channelDeliveryStore.linkMessage(eventId, userMessageId);
+      channelDeliveryStore.markProcessed(eventId);
+
+      if (replyCallbackUrl) {
+        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl);
+      }
     } 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);
+      log.error({ err, conversationId }, 'Background channel message processing failed');
+      channelDeliveryStore.recordProcessingFailure(eventId, err);
     }
-  }
+  })();
+}
 
-  // Only look up the assistant reply when processing succeeded for a new
-  // (non-duplicate) message.  For duplicates or failed processing, returning
-  // a stale assistant message could cause the caller to resend old replies.
-  let assistantMessage: RuntimeMessagePayload | undefined;
-  if (processingSucceeded) {
-    const msgs = conversationStore.getMessages(result.conversationId);
-    for (let i = msgs.length - 1; i >= 0; i--) {
-      if (msgs[i].role === 'assistant') {
-        let parsed: unknown;
-        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 replyAttachments: RuntimeAttachmentMetadata[] = linked.map((a) => ({
-          id: a.id,
-          filename: a.originalFilename,
-          mimeType: a.mimeType,
-          sizeBytes: a.sizeBytes,
-          kind: a.kind,
-        }));
-
-        // Include the reply if it has text or attachments
-        if (rendered.text || replyAttachments.length > 0) {
-          assistantMessage = {
-            id: msgs[i].id,
-            role: 'assistant',
-            content: rendered.text,
-            timestamp: new Date(msgs[i].createdAt).toISOString(),
-            attachments: replyAttachments,
-          };
-        }
-        break;
+async function deliverReplyViaCallback(
+  conversationId: string,
+  externalChatId: string,
+  callbackUrl: string,
+): Promise<void> {
+  const msgs = conversationStore.getMessages(conversationId);
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    if (msgs[i].role === 'assistant') {
+      let parsed: unknown;
+      try { parsed = JSON.parse(msgs[i].content); } catch { parsed = msgs[i].content; }
+      const rendered = renderHistoryContent(parsed);
+
+      const linked = attachmentsStore.getAttachmentMetadataForMessage(msgs[i].id);
+      const replyAttachments: RuntimeAttachmentMetadata[] = linked.map((a) => ({
+        id: a.id,
+        filename: a.originalFilename,
+        mimeType: a.mimeType,
+        sizeBytes: a.sizeBytes,
+        kind: a.kind,
+      }));
+
+      if (rendered.text || replyAttachments.length > 0) {
+        await deliverChannelReply(callbackUrl, {
+          chatId: externalChatId,
+          text: rendered.text || undefined,
+          attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
+        });
       }
+      break;
     }
   }
-
-  return Response.json({
-    accepted: result.accepted,
-    duplicate: result.duplicate,
-    eventId: result.eventId,
-    ...(assistantMessage ? { assistantMessage } : {}),
-  });
 }
 
 export function handleListDeadLetters(): Response {
-  const events = channelDeliveryStore.getDeadLetterEvents("self");
+  const events = channelDeliveryStore.getDeadLetterEvents();
   return Response.json({ events });
 }
 
@@ -302,7 +340,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 +364,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}`);
+}

package/src/schedule/recurrence-types.ts

@@ -0,0 +1,67 @@
+export type ScheduleSyntax = 'cron' | 'rrule';
+
+/**
+ * Detect whether an expression string is cron or RRULE syntax.
+ * Returns null for ambiguous or invalid expressions.
+ */
+export function detectScheduleSyntax(expression: string): ScheduleSyntax | null {
+  if (!expression || typeof expression !== 'string') return null;
+  const trimmed = expression.trim();
+  if (!trimmed) return null;
+
+  // RRULE detection: starts with RRULE:, DTSTART, or contains FREQ=
+  if (/^(RRULE:|DTSTART)/m.test(trimmed) || /FREQ=/i.test(trimmed)) {
+    return 'rrule';
+  }
+
+  // Cron detection: 5 space-separated fields
+  const fields = trimmed.split(/\s+/);
+  if (fields.length === 5) {
+    // Basic sanity check: each field should match cron-like characters
+    const cronFieldPattern = /^[\d\*\/\-\,\?LW#]+$/;
+    if (fields.every(f => cronFieldPattern.test(f))) {
+      return 'cron';
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Normalize schedule syntax from tool/API inputs.
+ * Resolution order:
+ * 1. If explicit `syntax` is provided, use it
+ * 2. If `expression` is provided, auto-detect from expression
+ * 3. If `legacyCronExpression` is provided, treat as cron
+ * 4. Return null if nothing resolved
+ */
+export function normalizeScheduleSyntax(input: {
+  syntax?: ScheduleSyntax;
+  expression?: string;
+  legacyCronExpression?: string;
+}): { syntax: ScheduleSyntax; expression: string } | null {
+  // Explicit syntax + expression
+  if (input.syntax && input.expression) {
+    return { syntax: input.syntax, expression: input.expression };
+  }
+
+  // Auto-detect from expression
+  if (input.expression) {
+    const detected = detectScheduleSyntax(input.expression);
+    if (detected) {
+      return { syntax: detected, expression: input.expression };
+    }
+    // If we have an explicit syntax but couldn't detect, trust the explicit syntax
+    if (input.syntax) {
+      return { syntax: input.syntax, expression: input.expression };
+    }
+    return null;
+  }
+
+  // Legacy cron_expression fallback
+  if (input.legacyCronExpression) {
+    return { syntax: 'cron', expression: input.legacyCronExpression };
+  }
+
+  return null;
+}