@omg-dev/server 0.4.24

package/src/triggers.ts

@@ -0,0 +1,837 @@
+// Cron + event triggers for vibes apps.
+//
+// User-facing API:
+//   import { cron, on, emit } from "@omg-dev/server"
+//
+//   export const purge = cron("0 3 * * *", async (ctx) => { ... })
+//   export const welcome = on("user.signup", async (ctx, payload) => { ... })
+//   await emit("user.signup", { userId, email })
+//
+// Runtime modes:
+//   - VIBES_MODE=prod (default in deployed bundles): emit() POSTs to the
+//     in-VM agent's /_emit endpoint, which forwards to the orchestrator
+//     queue. Cron and on are fired by the orchestrator via POST to
+//     /_vibes/dispatch on this server.
+//   - VIBES_MODE=dev (set by the vite-plugin during `bun dev`): emit() uses
+//     an in-process pub/sub bus; cron is scheduled with a setTimeout/clear
+//     loop reading the parsed cron expression. Same handler functions run
+//     in both modes.
+//
+// The vite-plugin scanner detects `cron("…", fn)` and `on("…", fn)` call
+// sites in functions/*.ts at build/HMR time and emits .vibes/triggers.json
+// — that file is the source of truth for which handlers are registered.
+// This module reads it at boot (createVibesServer) and (re-)registers.
+
+import path from "node:path"
+import fs from "node:fs"
+import { ctxStore, type VibesCtx } from "./ctx.ts"
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export type CronHandler = (ctx: VibesCtx) => unknown | Promise<unknown>
+export type EventHandler<T = unknown> = (ctx: VibesCtx, payload: T) => unknown | Promise<unknown>
+
+/**
+ * Schedule a function to run on a cron expression (UTC, 5-field syntax).
+ * The schedule must be a literal string — dynamic values will be rejected by
+ * the build-time scanner so the orchestrator can register the trigger.
+ *
+ * Returns the handler unchanged so it can also be invoked directly in tests.
+ */
+export function cron(schedule: string, handler: CronHandler): CronHandler {
+  // Function is also registered side-effect-free here so unit tests that
+  // import the file get the registration too (the live registry is populated
+  // explicitly via registerTrigger() at boot from .vibes/triggers.json).
+  return handler
+}
+
+/**
+ * Subscribe a function to an event topic. The topic must be a literal string.
+ */
+export function on<T = unknown>(topic: string, handler: EventHandler<T>): EventHandler<T> {
+  return handler
+}
+
+/**
+ * Emit an event. Mode-aware: posts to the orchestrator in prod; runs
+ * subscribers in-process in dev.
+ *
+ * Payload is JSON-serialized; total size capped at 64 KB (matched against
+ * the orchestrator-side limit).
+ */
+export async function emit(topic: string, payload: unknown = null): Promise<{ subscriberCount: number }> {
+  if (vibesMode() === "dev") {
+    return emitInProcess(topic, payload)
+  }
+  return emitToOrchestrator(topic, payload)
+}
+
+/**
+ * Schedule a one-shot delayed fire of `topic`. Same fan-out semantics as
+ * `emit()` (every `on(topic, …)` subscriber receives one delivery), but
+ * each delivery runs at `atMs` instead of immediately.
+ *
+ * `atMs` is unix milliseconds. Past timestamps fire ASAP. The orchestrator
+ * caps the future horizon at 365 days.
+ *
+ * Returns `{ eventId, subscriberCount, scheduledFor }`. Hold onto `eventId`
+ * if you might need to `cancel(eventId)` before it fires.
+ *
+ * Example:
+ *   const { eventId } = await schedule(reminder.dueAt, "reminder.due", { id })
+ *   // …later, if user deletes the reminder:
+ *   await cancel(eventId)
+ */
+export async function schedule(
+  atMs: number,
+  topic: string,
+  payload: unknown = null,
+): Promise<{ eventId: string; subscriberCount: number; scheduledFor: number }> {
+  if (!Number.isFinite(atMs) || atMs < 0) {
+    throw new Error(`schedule("${topic}"): at must be a unix-ms number`)
+  }
+  if (!topic || typeof topic !== "string") {
+    throw new Error("schedule: topic required")
+  }
+  if (vibesMode() === "dev") {
+    return scheduleInProcess(atMs, topic, payload)
+  }
+  return scheduleToOrchestrator(atMs, topic, payload)
+}
+
+/**
+ * Cancel the pending deliveries created by a previous `schedule()`. At-most-
+ * once semantics: anything already claimed or fired is past the cancel
+ * window and is left untouched.
+ *
+ * Returns `{ cancelled }`, the number of pending deliveries dropped. Zero
+ * is a valid response meaning "nothing left to cancel" (already fired, or
+ * never scheduled with this eventId).
+ */
+export async function cancel(eventId: string): Promise<{ cancelled: number }> {
+  if (!eventId || typeof eventId !== "string") {
+    throw new Error("cancel: eventId required")
+  }
+  if (vibesMode() === "dev") {
+    return cancelInProcess(eventId)
+  }
+  return cancelOnOrchestrator(eventId)
+}
+
+// ── Registry ─────────────────────────────────────────────────────────────────
+
+interface TriggerEntry {
+  // dispatch identifier — what arrives in POST /_vibes/dispatch body.handler
+  // Convention: "<file-basename>.<exportName>"
+  handler: string
+  kind: "cron" | "on" | "storage:upload" | "storage:delete"
+  key: string // cron expression / topic; empty for storage hooks
+  module: string // file path to import (dev) — ignored when `mod` is set
+  exportName: string
+  mod?: Record<string, unknown> // preloaded for prod bundles
+}
+
+interface ResolvedHandler {
+  entry: TriggerEntry
+  fn: CronHandler | EventHandler
+}
+
+const triggerRegistry = new Map<string, ResolvedHandler>()
+// Event subscriptions, indexed by topic for fast emit() lookup.
+const topicSubscribers = new Map<string, Set<string>>() // topic → set of handler names
+// Storage hooks, indexed by kind. Fired by the auto-injected
+// /api/_storage/notify route after a successful upload / delete.
+const storageHookHandlers = new Map<"storage:upload" | "storage:delete", Set<string>>()
+
+// In-process dev scheduler state.
+const cronIntervals = new Map<string, ReturnType<typeof setInterval>>()
+
+// ── Cron driver ──────────────────────────────────────────────────────────────
+// Which machinery fires cron() handlers:
+//   - "orchestrator" (prod default): the orchestrator's ticker enqueues
+//     deliveries and the dispatcher POSTs /_vibes/dispatch into this server.
+//     Requires the app to be an orchestrator-managed deploy — a plain
+//     container (control-plane, self-host bundle) never receives dispatches
+//     and its crons silently never fire.
+//   - "in-process": the same setInterval scheduler dev mode uses, armed at
+//     registerTriggers() time. For hosts that run as standalone containers.
+// Dev mode always schedules in-process regardless of this setting. Only
+// affects cron — emit()/schedule() routing still follows vibesMode().
+
+export type CronDriver = "orchestrator" | "in-process"
+
+let _cronDriver: CronDriver | null = null
+
+export function setCronDriver(driver: CronDriver): void {
+  if (driver !== "orchestrator" && driver !== "in-process") {
+    throw new Error(`[vibes:triggers] unknown cron driver ${JSON.stringify(driver)} — expected "orchestrator" or "in-process"`)
+  }
+  _cronDriver = driver
+}
+
+function cronDriver(): CronDriver {
+  if (_cronDriver) return _cronDriver
+  const env = (typeof process !== "undefined" ? process.env?.VIBES_CRON_DRIVER : undefined) ?? ""
+  if (env === "") return "orchestrator"
+  if (env !== "orchestrator" && env !== "in-process") {
+    throw new Error(`[vibes:triggers] unknown VIBES_CRON_DRIVER ${JSON.stringify(env)} — expected "orchestrator" or "in-process"`)
+  }
+  return env
+}
+
+/** Clear everything — called on HMR reload. */
+export function clearTriggers(): void {
+  for (const interval of cronIntervals.values()) clearInterval(interval)
+  cronIntervals.clear()
+  triggerRegistry.clear()
+  topicSubscribers.clear()
+  storageHookHandlers.clear()
+}
+
+/** Load triggers from .vibes/triggers.json (called at createVibesServer boot). */
+export async function loadTriggersFromFile(root: string): Promise<TriggerEntry[]> {
+  const triggersPath = path.join(root, ".vibes", "triggers.json")
+  if (!fs.existsSync(triggersPath)) return []
+  try {
+    const raw = fs.readFileSync(triggersPath, "utf-8")
+    const parsed = JSON.parse(raw) as TriggerEntry[]
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    console.error("[vibes:triggers] failed to read triggers.json:", err)
+    return []
+  }
+}
+
+/**
+ * Populate the registry from a parsed trigger list. Either resolves each
+ * handler via dynamic import (dev) or reads it from the preloaded `mod`
+ * field (prod bundle). Idempotent.
+ */
+export async function registerTriggers(entries: TriggerEntry[]): Promise<void> {
+  clearTriggers()
+  let registeredFirstTime = false
+  for (const e of entries) {
+    let fn: any
+    if (e.mod) {
+      fn = e.mod[e.exportName]
+    } else {
+      // Bun's import resolver rejected `?t=Date.now()` cache-busters on
+      // absolute file paths in dev (the import returned undefined exports
+      // silently). Plain dynamic import works the first time; rely on
+      // clearTriggers() + module-cache bust at HMR for re-registration.
+      try {
+        const mod = await import(e.module)
+        fn = mod[e.exportName]
+        registeredFirstTime = true
+      } catch (err) {
+        console.error(`[vibes:triggers] import ${e.module}#${e.exportName} failed:`, err)
+        continue
+      }
+    }
+    if (typeof fn !== "function") {
+      console.error(`[vibes:triggers] ${e.module}#${e.exportName} is not a function (got ${typeof fn}) — skipping`)
+      continue
+    }
+    triggerRegistry.set(e.handler, { entry: e, fn })
+    if (e.kind === "on") {
+      if (!topicSubscribers.has(e.key)) topicSubscribers.set(e.key, new Set())
+      topicSubscribers.get(e.key)!.add(e.handler)
+    } else if (e.kind === "storage:upload" || e.kind === "storage:delete") {
+      if (!storageHookHandlers.has(e.kind)) storageHookHandlers.set(e.kind, new Set())
+      storageHookHandlers.get(e.kind)!.add(e.handler)
+    }
+  }
+  void registeredFirstTime // suppress unused — kept for future HMR diff
+  const inProcessCron = vibesMode() === "dev" || cronDriver() === "in-process"
+  if (inProcessCron) {
+    scheduleAllCronInProcess()
+  }
+  console.log(
+    `[vibes:triggers] registered ${entries.length} trigger(s) — mode=${vibesMode()}, cron=${inProcessCron ? "in-process" : "orchestrator"}`,
+  )
+}
+
+/** Snapshot of the registry — used by the in-dev Inspect endpoints. */
+export function listTriggers(): Array<{
+  handler: string
+  kind: "cron" | "on" | "storage:upload" | "storage:delete"
+  key: string
+}> {
+  return Array.from(triggerRegistry.values()).map(({ entry }) => ({
+    handler: entry.handler,
+    kind: entry.kind,
+    key: entry.key,
+  }))
+}
+
+/**
+ * Fan out a storage event to every registered `storage.onUpload` /
+ * `onDelete` handler. Called by the auto-injected /api/_storage/notify
+ * route after a successful PUT/DELETE round-trips back from the browser.
+ *
+ * Handlers run in-process (no orchestrator dispatcher round-trip) — the
+ * notify is best-effort fire-and-forget from the SDK's perspective. A
+ * dropped notify means the hook doesn't fire; the storage object itself
+ * is unaffected.
+ *
+ * Returns the number of handlers invoked. Each handler's failure is
+ * logged but doesn't bubble — one bad handler shouldn't block siblings.
+ */
+export async function dispatchStorageEvent(
+  kind: "storage:upload" | "storage:delete",
+  evt: {
+    key: string
+    size?: number
+    contentType?: string
+    userId?: string | null
+    scope?: "user" | "app"
+  },
+): Promise<number> {
+  const names = storageHookHandlers.get(kind)
+  if (!names || names.size === 0) return 0
+  let fired = 0
+  // We don't have access to ctxStore here without a circular import — the
+  // caller is responsible for running this inside its own ctxStore.run().
+  await Promise.all(Array.from(names).map(async name => {
+    const resolved = triggerRegistry.get(name)
+    if (!resolved) return
+    try {
+      // ctx is constructed by the caller via ctxStore.run() — handlers
+      // read `ctx.userId` from there if they need to attribute the event.
+      // We pass a stable payload shape that matches the @omg-dev/server
+      // `StorageEvent` type.
+      const handler = resolved.fn as (
+        ctx: any,
+        evt: any,
+      ) => unknown | Promise<unknown>
+      const payload = kind === "storage:upload"
+        ? { kind: "upload", key: evt.key, size: evt.size ?? 0, contentType: evt.contentType ?? "", userId: evt.userId ?? null }
+        : { kind: "delete", key: evt.key, userId: evt.userId ?? null }
+      // Pass a thin ctx-like object so handlers compiled against VibesCtx
+      // type still see the userId.
+      const ctxLike = { userId: evt.userId ?? null, system: true }
+      await handler(ctxLike, payload)
+      fired++
+    } catch (err) {
+      console.error(`[vibes:storage] handler ${name} threw:`, err)
+    }
+  }))
+  return fired
+}
+
+// ── Dispatch (orchestrator → handler) ───────────────────────────────────────
+
+interface DispatchBody {
+  handler: string
+  payload?: string | null // JSON-encoded payload (events) or null (cron)
+  deliveryId?: string
+  triggerId?: string
+  eventId?: string
+}
+
+/**
+ * Invoke a registered handler. Returns a Response so the agent can pass
+ * it back to the orchestrator dispatcher loop, which keys retry/done on
+ * the status code.
+ */
+export async function dispatchHandler(body: DispatchBody): Promise<Response> {
+  const resolved = triggerRegistry.get(body.handler)
+  if (!resolved) {
+    return new Response(JSON.stringify({ error: `unknown handler: ${body.handler}` }), {
+      status: 404,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+  let payload: unknown = null
+  if (body.payload && body.payload !== "null") {
+    try {
+      payload = JSON.parse(body.payload)
+    } catch (err) {
+      return new Response(JSON.stringify({ error: `payload parse: ${(err as Error).message}` }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      })
+    }
+  }
+
+  // Run inside an empty ctx — trigger handlers have no user identity by
+  // default. If a handler needs to act as a specific user it can do so
+  // explicitly via the auth APIs.
+  try {
+    await ctxStore.run({ userId: null, system: true } as VibesCtx, async () => {
+      if (resolved.entry.kind === "cron") {
+        await (resolved.fn as CronHandler)({ userId: null, system: true } as VibesCtx)
+      } else {
+        await (resolved.fn as EventHandler)({ userId: null, system: true } as VibesCtx, payload)
+      }
+    })
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    console.error(`[vibes:triggers] handler ${body.handler} threw:`, err)
+    return new Response(JSON.stringify({ error: msg }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}
+
+// ── Emit paths ───────────────────────────────────────────────────────────────
+
+const MAX_EMIT_BYTES = 64 * 1024
+// Track recent in-process emits so the dev Inspect view can surface them.
+// Bounded ring so a long-running dev session doesn't OOM.
+const DEV_EMIT_RING = 200
+const recentDevEmits: Array<{
+  id: string
+  topic: string
+  payload: unknown
+  subscriberCount: number
+  createdAt: number
+}> = []
+const recentDevDeliveries: Array<{
+  id: string
+  eventId?: string
+  handler: string
+  // "pending" is for scheduled fires that haven't elapsed yet; they appear
+  // in the Inspect Scheduled section and flip to done/failed on fire.
+  status: "pending" | "done" | "failed"
+  attempts: number
+  lastError?: string
+  createdAt?: number
+  runAt: number
+  doneAt?: number
+}> = []
+
+function pushBounded<T>(arr: T[], v: T, max: number): void {
+  arr.unshift(v)
+  if (arr.length > max) arr.length = max
+}
+
+function emitInProcess(topic: string, payload: unknown): { subscriberCount: number } {
+  const payloadStr = JSON.stringify(payload ?? null)
+  if (payloadStr.length > MAX_EMIT_BYTES) {
+    throw new Error(`emit("${topic}"): payload exceeds ${MAX_EMIT_BYTES} bytes`)
+  }
+  const subs = topicSubscribers.get(topic)
+  const subList = subs ? Array.from(subs) : []
+  const ev = {
+    id: `evt_dev_${Date.now()}_${Math.floor(Math.random() * 4096).toString(16)}`,
+    topic,
+    payload,
+    subscriberCount: subList.length,
+    createdAt: Date.now(),
+  }
+  pushBounded(recentDevEmits, ev, DEV_EMIT_RING)
+
+  // Fire-and-forget per subscriber; record into the dev deliveries ring.
+  for (const handler of subList) {
+    const resolved = triggerRegistry.get(handler)
+    if (!resolved) continue
+    const start = Date.now()
+    void (async () => {
+      try {
+        await (resolved.fn as EventHandler)(
+          { userId: null, system: true } as VibesCtx,
+          payload,
+        )
+        pushBounded(recentDevDeliveries, {
+          id: `dlv_dev_${start}_${Math.floor(Math.random() * 4096).toString(16)}`,
+          eventId: ev.id,
+          handler,
+          status: "done" as const,
+          attempts: 1,
+          createdAt: start,
+          runAt: start,
+          doneAt: Date.now(),
+        }, DEV_EMIT_RING)
+      } catch (err) {
+        pushBounded(recentDevDeliveries, {
+          id: `dlv_dev_${start}_${Math.floor(Math.random() * 4096).toString(16)}`,
+          eventId: ev.id,
+          handler,
+          status: "failed" as const,
+          attempts: 1,
+          lastError: err instanceof Error ? err.message : String(err),
+          createdAt: start,
+          runAt: start,
+          doneAt: Date.now(),
+        }, DEV_EMIT_RING)
+        console.error(`[vibes:triggers] dev emit ${topic} → ${handler} threw:`, err)
+      }
+    })()
+  }
+  return { subscriberCount: subList.length }
+}
+
+async function emitToOrchestrator(topic: string, payload: unknown): Promise<{ subscriberCount: number }> {
+  const payloadStr = JSON.stringify(payload ?? null)
+  if (payloadStr.length > MAX_EMIT_BYTES) {
+    throw new Error(`emit("${topic}"): payload exceeds ${MAX_EMIT_BYTES} bytes`)
+  }
+  const url = "http://localhost:8080/_emit"
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ topic, payload: JSON.parse(payloadStr) }),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`emit("${topic}") agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+  const body = (await res.json()) as { eventId?: string; subscriberCount?: number }
+  return { subscriberCount: body.subscriberCount ?? 0 }
+}
+
+// ── schedule() dev path ──────────────────────────────────────────────────────
+//
+// Dev mode runs entirely in-process: store the pending fire in a Map keyed
+// by eventId so cancel() can find it, setTimeout to the fire moment, and
+// invoke the same subscriber loop emitInProcess uses. Recorded into the
+// recentDevDeliveries ring with runAt = future so the Inspect Activity tab
+// shows it under "Scheduled" before it fires.
+
+interface PendingScheduledFire {
+  timer: ReturnType<typeof setTimeout>
+  topic: string
+  payload: unknown
+  fireAt: number
+  // Per-subscriber delivery IDs we wrote into recentDevDeliveries with
+  // status=pending. cancelInProcess uses these to filter them back out.
+  deliveryIds: string[]
+}
+const pendingScheduledFires = new Map<string, PendingScheduledFire>()
+
+function devId(prefix: string): string {
+  return `${prefix}_dev_${Date.now()}_${Math.floor(Math.random() * 4096).toString(16)}`
+}
+
+function scheduleInProcess(
+  atMs: number,
+  topic: string,
+  payload: unknown,
+): { eventId: string; subscriberCount: number; scheduledFor: number } {
+  const payloadStr = JSON.stringify(payload ?? null)
+  if (payloadStr.length > MAX_EMIT_BYTES) {
+    throw new Error(`schedule("${topic}"): payload exceeds ${MAX_EMIT_BYTES} bytes`)
+  }
+  const subs = topicSubscribers.get(topic)
+  const subList = subs ? Array.from(subs) : []
+  const eventId = devId("evt")
+  const now = Date.now()
+
+  // Record the event row so the Inspect Events list shows the scheduled
+  // emit immediately, even though deliveries haven't fired yet.
+  pushBounded(recentDevEmits, {
+    id: eventId,
+    topic,
+    payload,
+    subscriberCount: subList.length,
+    createdAt: now,
+  }, DEV_EMIT_RING)
+
+  // Pre-create the pending delivery rows so the Activity tab shows them in
+  // the "Scheduled" section right away. We update them in place when the
+  // timer fires (or remove them on cancel).
+  const deliveryIds: string[] = []
+  for (const handler of subList) {
+    const id = devId("dlv")
+    deliveryIds.push(id)
+    pushBounded(recentDevDeliveries, {
+      id,
+      eventId,
+      handler,
+      status: "pending" as const,
+      attempts: 0,
+      createdAt: now,
+      runAt: atMs,
+    }, DEV_EMIT_RING)
+  }
+
+  const delay = Math.max(0, atMs - now)
+  const timer = setTimeout(() => {
+    pendingScheduledFires.delete(eventId)
+    // Fire each subscriber in parallel; update the pre-recorded delivery
+    // entries with done/failed status.
+    for (let i = 0; i < subList.length; i++) {
+      const handler = subList[i]
+      const id = deliveryIds[i]
+      const resolved = triggerRegistry.get(handler)
+      if (!resolved) continue
+      const startedAt = Date.now()
+      void (async () => {
+        try {
+          await (resolved.fn as EventHandler)(
+            { userId: null, system: true } as VibesCtx,
+            payload,
+          )
+          updateDevDelivery(id, {
+            status: "done",
+            attempts: 1,
+            doneAt: Date.now(),
+            runAt: startedAt,
+          })
+        } catch (err) {
+          updateDevDelivery(id, {
+            status: "failed",
+            attempts: 1,
+            doneAt: Date.now(),
+            runAt: startedAt,
+            lastError: err instanceof Error ? err.message : String(err),
+          })
+          console.error(`[vibes:triggers] dev schedule ${topic} → ${handler} threw:`, err)
+        }
+      })()
+    }
+  }, delay)
+
+  pendingScheduledFires.set(eventId, { timer, topic, payload, fireAt: atMs, deliveryIds })
+
+  return { eventId, subscriberCount: subList.length, scheduledFor: atMs }
+}
+
+function cancelInProcess(eventId: string): { cancelled: number } {
+  const pending = pendingScheduledFires.get(eventId)
+  if (!pending) {
+    return { cancelled: 0 }
+  }
+  clearTimeout(pending.timer)
+  pendingScheduledFires.delete(eventId)
+  // Drop the pre-recorded pending deliveries from the ring so the
+  // Inspect Scheduled section doesn't keep showing them.
+  const ids = new Set(pending.deliveryIds)
+  for (let i = recentDevDeliveries.length - 1; i >= 0; i--) {
+    if (ids.has(recentDevDeliveries[i].id)) recentDevDeliveries.splice(i, 1)
+  }
+  return { cancelled: pending.deliveryIds.length }
+}
+
+function updateDevDelivery(
+  id: string,
+  patch: Partial<(typeof recentDevDeliveries)[number]>,
+): void {
+  const i = recentDevDeliveries.findIndex((d) => d.id === id)
+  if (i < 0) return
+  recentDevDeliveries[i] = { ...recentDevDeliveries[i], ...patch }
+}
+
+// ── schedule() prod path ─────────────────────────────────────────────────────
+
+async function scheduleToOrchestrator(
+  atMs: number,
+  topic: string,
+  payload: unknown,
+): Promise<{ eventId: string; subscriberCount: number; scheduledFor: number }> {
+  const payloadStr = JSON.stringify(payload ?? null)
+  if (payloadStr.length > MAX_EMIT_BYTES) {
+    throw new Error(`schedule("${topic}"): payload exceeds ${MAX_EMIT_BYTES} bytes`)
+  }
+  const url = "http://localhost:8080/_schedule"
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      topic,
+      payload: JSON.parse(payloadStr),
+      runAt: atMs,
+    }),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`schedule("${topic}") agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+  const body = (await res.json()) as {
+    eventId?: string
+    subscriberCount?: number
+    runAt?: number
+  }
+  return {
+    eventId: body.eventId ?? "",
+    subscriberCount: body.subscriberCount ?? 0,
+    scheduledFor: body.runAt ?? atMs,
+  }
+}
+
+async function cancelOnOrchestrator(eventId: string): Promise<{ cancelled: number }> {
+  const url = `http://localhost:8080/_schedule/${encodeURIComponent(eventId)}`
+  const res = await fetch(url, { method: "DELETE" })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`cancel(${eventId}) agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+  const body = (await res.json()) as { cancelled?: number }
+  return { cancelled: body.cancelled ?? 0 }
+}
+
+// ── Dev in-process cron scheduler ────────────────────────────────────────────
+//
+// Schedule each cron trigger as a self-rescheduling setTimeout chain so we
+// can sleep until the exact next fire instead of polling every second.
+// Uses the same robfig-compatible parser via a tiny inline implementation.
+
+function scheduleAllCronInProcess(): void {
+  for (const interval of cronIntervals.values()) clearInterval(interval)
+  cronIntervals.clear()
+  for (const { entry } of triggerRegistry.values()) {
+    if (entry.kind !== "cron") continue
+    scheduleOneCron(entry.handler, entry.key)
+  }
+}
+
+function scheduleOneCron(handlerName: string, expr: string): void {
+  const tickFn = async () => {
+    const resolved = triggerRegistry.get(handlerName)
+    if (!resolved) return
+    const start = Date.now()
+    try {
+      await (resolved.fn as CronHandler)({ userId: null, system: true } as VibesCtx)
+      pushBounded(recentDevDeliveries, {
+        id: `dlv_dev_${start}_${Math.floor(Math.random() * 4096).toString(16)}`,
+        handler: handlerName,
+        status: "done" as const,
+        attempts: 1,
+        createdAt: start,
+        runAt: start,
+        doneAt: Date.now(),
+      }, DEV_EMIT_RING)
+    } catch (err) {
+      pushBounded(recentDevDeliveries, {
+        id: `dlv_dev_${start}_${Math.floor(Math.random() * 4096).toString(16)}`,
+        handler: handlerName,
+        status: "failed" as const,
+        attempts: 1,
+        lastError: err instanceof Error ? err.message : String(err),
+        createdAt: start,
+        runAt: start,
+        doneAt: Date.now(),
+      }, DEV_EMIT_RING)
+      console.error(`[vibes:triggers] dev cron ${handlerName} threw:`, err)
+    }
+  }
+  // Compute next fire on every iteration to avoid drift. We sleep until the
+  // next scheduled tick rather than polling every minute.
+  const reschedule = () => {
+    const next = nextCronTime(expr, new Date())
+    if (!next) {
+      console.error(`[vibes:triggers] dev cron ${handlerName}: invalid expr ${expr}`)
+      return
+    }
+    const wait = Math.max(0, next.getTime() - Date.now())
+    const timer = setTimeout(() => {
+      void tickFn().finally(reschedule)
+    }, wait)
+    cronIntervals.set(handlerName, timer as unknown as ReturnType<typeof setInterval>)
+  }
+  reschedule()
+}
+
+// ── Inline cron expression evaluator ─────────────────────────────────────────
+// Minimal subset of standard cron: 5 fields (minute hour dom month dow), with
+// `*`, `*/N`, comma lists, ranges. Sufficient for the patterns vibes apps will
+// declare. For richer expressions the orchestrator's robfig parser is the
+// source of truth in prod.
+
+function nextCronTime(expr: string, after: Date): Date | null {
+  try {
+    const fields = expr.trim().split(/\s+/)
+    if (fields.length !== 5) return null
+    const matchers = fields.map((f, i) => parseField(f, FIELD_BOUNDS[i]))
+    // Brute-force scan up to 4 years ahead (covers every leap-year edge).
+    let t = new Date(after.getTime() + 60_000 - (after.getTime() % 60_000))
+    const limit = t.getTime() + 4 * 365 * 24 * 60 * 60 * 1000
+    while (t.getTime() < limit) {
+      if (
+        matchers[0]!(t.getUTCMinutes()) &&
+        matchers[1]!(t.getUTCHours()) &&
+        matchers[2]!(t.getUTCDate()) &&
+        matchers[3]!(t.getUTCMonth() + 1) &&
+        matchers[4]!(t.getUTCDay())
+      ) {
+        return t
+      }
+      t = new Date(t.getTime() + 60_000)
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+const FIELD_BOUNDS: Array<[number, number]> = [
+  [0, 59], // minute
+  [0, 23], // hour
+  [1, 31], // dom
+  [1, 12], // month
+  [0, 6],  // dow
+]
+
+function parseField(field: string, [lo, hi]: [number, number]): (v: number) => boolean {
+  const allowed = new Set<number>()
+  for (const part of field.split(",")) {
+    if (part === "*") {
+      for (let i = lo; i <= hi; i++) allowed.add(i)
+    } else if (part.includes("*/")) {
+      const [, stepStr] = part.split("*/")
+      const step = parseInt(stepStr!, 10)
+      if (!Number.isFinite(step) || step <= 0) continue
+      for (let i = lo; i <= hi; i += step) allowed.add(i)
+    } else if (part.includes("-")) {
+      const [a, b] = part.split("-").map((s) => parseInt(s, 10))
+      if (Number.isFinite(a!) && Number.isFinite(b!)) {
+        for (let i = a!; i <= b!; i++) allowed.add(i)
+      }
+    } else if (part.includes("/")) {
+      // a/b: starts at a, then a+b, a+2b, ...
+      const [aStr, bStr] = part.split("/")
+      const a = parseInt(aStr!, 10)
+      const b = parseInt(bStr!, 10)
+      if (Number.isFinite(a) && Number.isFinite(b) && b > 0) {
+        for (let i = a; i <= hi; i += b) allowed.add(i)
+      }
+    } else {
+      const n = parseInt(part, 10)
+      if (Number.isFinite(n)) allowed.add(n)
+    }
+  }
+  return (v: number) => allowed.has(v)
+}
+
+// ── Mode detection ───────────────────────────────────────────────────────────
+
+let _vibesMode: "dev" | "prod" | null = null
+function vibesMode(): "dev" | "prod" {
+  if (_vibesMode) return _vibesMode
+  // VIBES_MODE explicitly set by vite-plugin / deploy runtime wins.
+  const env = (typeof process !== "undefined" ? process.env?.VIBES_MODE : undefined) ?? ""
+  _vibesMode = env === "dev" ? "dev" : "prod"
+  return _vibesMode
+}
+
+// ── Dev Inspect data accessors ───────────────────────────────────────────────
+//
+// In dev mode, the dashboard's Inspect tabs read the in-memory rings
+// directly via /_vibes/inspect/* routes registered on the @omg-dev/server
+// instance. In prod they hit the orchestrator's sqld-backed endpoints.
+
+export function devInspectTriggers() {
+  return Array.from(triggerRegistry.values()).map(({ entry }, i) => ({
+    id: `trg_dev_${i}_${entry.handler}`,
+    kind: entry.kind,
+    key: entry.key,
+    handler: entry.handler,
+    version: 0,
+    nextFireAt: 0,
+    createdAt: 0,
+  }))
+}
+
+export function devInspectDeliveries() {
+  return recentDevDeliveries
+}
+
+export function devInspectEvents() {
+  return recentDevEmits
+}