@bbigbang/core 0.1.0

package/dist/web/agentReminders.js

@@ -0,0 +1,1668 @@
+import { randomUUID } from 'node:crypto';
+export const AGENT_REMINDER_TIMEZONE = 'Asia/Shanghai';
+export const AGENT_REMINDER_POLL_INTERVAL_MS = 5_000;
+const OPEN_REMINDER_OCCURRENCE_STATUSES = ['pending', 'dispatched', 'awaiting_review', 'failed', 'snoozed'];
+function intervalMs(unit, value) {
+    if (!unit || !value || value <= 0)
+        return null;
+    switch (unit) {
+        case 'hour':
+            return value * 60 * 60 * 1000;
+        case 'day':
+            return value * 24 * 60 * 60 * 1000;
+        case 'week':
+            return value * 7 * 24 * 60 * 60 * 1000;
+    }
+}
+function countReminderOccurrences(db, reminderId) {
+    const row = db.prepare(`SELECT COUNT(*) as count
+       FROM agent_reminder_occurrences
+      WHERE reminder_id = ?
+        AND COALESCE(trigger_kind, 'scheduled') = 'scheduled'`).get(reminderId);
+    return row?.count ?? 0;
+}
+function countOpenReminderOccurrences(db, reminderId) {
+    const row = db.prepare(`SELECT COUNT(*) as count
+       FROM agent_reminder_occurrences
+      WHERE reminder_id = ?
+        AND status IN ('pending', 'dispatched', 'awaiting_review', 'failed', 'snoozed')`).get(reminderId);
+    return row?.count ?? 0;
+}
+export function isOpenReminderOccurrenceStatus(status) {
+    return OPEN_REMINDER_OCCURRENCE_STATUSES.includes(status);
+}
+function normalizePositiveInt(value) {
+    if (value == null)
+        return null;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return null;
+    return Math.floor(parsed);
+}
+function normalizeNullableTimestamp(value) {
+    if (value == null)
+        return null;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return null;
+    return Math.floor(parsed);
+}
+function normalizeRequiredText(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`${field} is required`);
+    }
+    return value.trim();
+}
+function normalizeReminderUpsertInput(request, existing) {
+    const title = 'title' in request && request.title !== undefined
+        ? normalizeRequiredText(request.title, 'title')
+        : existing?.title;
+    const promptText = 'promptText' in request && request.promptText !== undefined
+        ? normalizeRequiredText(request.promptText, 'promptText')
+        : existing?.promptText;
+    const scheduleKind = 'scheduleKind' in request && request.scheduleKind !== undefined
+        ? request.scheduleKind
+        : existing?.scheduleKind;
+    const startAt = 'startAt' in request && request.startAt !== undefined
+        ? normalizeNullableTimestamp(request.startAt)
+        : existing?.startAt ?? null;
+    const intervalUnit = 'intervalUnit' in request
+        ? (request.intervalUnit ?? null)
+        : (existing?.intervalUnit ?? null);
+    const intervalValue = 'intervalValue' in request
+        ? normalizePositiveInt(request.intervalValue)
+        : (existing?.intervalValue ?? null);
+    const endAt = 'endAt' in request
+        ? normalizeNullableTimestamp(request.endAt)
+        : (existing?.endAt ?? null);
+    const maxOccurrences = 'maxOccurrences' in request
+        ? normalizePositiveInt(request.maxOccurrences)
+        : (existing?.maxOccurrences ?? null);
+    if (!title)
+        throw new Error('title is required');
+    if (!promptText)
+        throw new Error('promptText is required');
+    if (scheduleKind !== 'one_time' && scheduleKind !== 'recurring') {
+        throw new Error('scheduleKind must be one_time or recurring');
+    }
+    if (!startAt)
+        throw new Error('startAt is required');
+    if (endAt != null && endAt < startAt) {
+        throw new Error('endAt must be greater than or equal to startAt');
+    }
+    if (scheduleKind === 'recurring') {
+        if (intervalUnit !== 'hour' && intervalUnit !== 'day' && intervalUnit !== 'week') {
+            throw new Error('intervalUnit is required for recurring reminders');
+        }
+        if (!intervalValue) {
+            throw new Error('intervalValue is required for recurring reminders');
+        }
+    }
+    return {
+        title,
+        promptText,
+        scheduleKind,
+        startAt,
+        intervalUnit: scheduleKind === 'recurring' ? intervalUnit : null,
+        intervalValue: scheduleKind === 'recurring' ? intervalValue : null,
+        endAt,
+        maxOccurrences: scheduleKind === 'recurring' ? maxOccurrences : null,
+    };
+}
+function computeNextRunAt(params) {
+    if (params.maxOccurrences != null && params.existingOccurrenceCount >= params.maxOccurrences) {
+        return null;
+    }
+    if (params.scheduleKind === 'one_time') {
+        if (params.existingOccurrenceCount > 0 || params.lastScheduledAt != null)
+            return null;
+        const candidate = params.startAt;
+        if (params.endAt != null && candidate > params.endAt)
+            return null;
+        return candidate;
+    }
+    const interval = intervalMs(params.intervalUnit, params.intervalValue);
+    if (!interval)
+        return null;
+    let candidate = params.lastScheduledAt != null
+        ? params.lastScheduledAt + interval
+        : params.startAt;
+    if (params.lastScheduledAt == null && candidate < params.now) {
+        const delta = params.now - params.startAt;
+        const steps = Math.ceil(delta / interval);
+        candidate = params.startAt + Math.max(0, steps) * interval;
+    }
+    if (params.endAt != null && candidate > params.endAt)
+        return null;
+    return candidate;
+}
+function mapOccurrenceRow(row) {
+    return {
+        occurrenceId: row.occurrenceId,
+        reminderId: row.reminderId,
+        scheduledFor: row.scheduledFor,
+        startedAt: row.startedAt,
+        completedAt: row.completedAt,
+        status: row.status,
+        taskId: row.taskId,
+        conversationId: row.conversationId,
+        threadRootId: row.threadRootId,
+        taskNumber: row.taskNumber,
+        taskTitle: row.taskTitle,
+        taskStatus: row.taskStatus,
+        error: row.error,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+function hasReminderTriggered(db, row) {
+    if (row.scheduleKind !== 'one_time')
+        return false;
+    if (row.lastScheduledAt != null)
+        return true;
+    return countReminderOccurrences(db, row.reminderId) > 0;
+}
+function isRetryableFailedOneTimeOccurrence(occurrence) {
+    return Boolean(occurrence
+        && occurrence.status === 'failed'
+        && !occurrence.taskId
+        && !occurrence.conversationId
+        && !occurrence.threadRootId);
+}
+function assertOneTimeScheduleStillMutable(db, row, request) {
+    if (!hasReminderTriggered(db, row))
+        return;
+    const scheduleChanged = (request.scheduleKind !== row.scheduleKind
+        || request.startAt !== row.startAt
+        || request.intervalUnit !== row.intervalUnit
+        || request.intervalValue !== row.intervalValue
+        || request.endAt !== row.endAt
+        || request.maxOccurrences !== row.maxOccurrences);
+    if (scheduleChanged) {
+        throw new Error('One-time reminder schedule cannot change after its first occurrence');
+    }
+}
+function ensureOneTimeOccurrenceSupportsReview(reminder) {
+    if (reminder.scheduleKind !== 'one_time')
+        return;
+    throw new Error('One-time reminder occurrences must use bigbang reminder submit-for-review before user approval');
+}
+function ensureOneTimeFollowUpActionAllowed(reminder, action) {
+    if (reminder.scheduleKind !== 'one_time')
+        return;
+    throw new Error(`One-time reminder occurrences do not support ${action}; edit the brief or abandon the reminder instead`);
+}
+function mapReminderRow(row, recentOccurrences = []) {
+    return {
+        reminderId: row.reminderId,
+        agentId: row.agentId,
+        targetUserId: row.targetUserId,
+        title: row.title,
+        promptText: row.promptText,
+        scheduleKind: row.scheduleKind,
+        intervalUnit: row.intervalUnit,
+        intervalValue: row.intervalValue,
+        startAt: row.startAt,
+        endAt: row.endAt,
+        maxOccurrences: row.maxOccurrences,
+        status: row.status,
+        timezone: row.timezone,
+        lastScheduledAt: row.lastScheduledAt,
+        nextRunAt: row.nextRunAt,
+        createdByUserId: row.createdByUserId,
+        createdByAgentId: row.createdByAgentId,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        recentOccurrences,
+    };
+}
+function appendReminderEvent(db, params) {
+    db.prepare(`INSERT INTO agent_reminder_events(
+       event_id, reminder_id, occurrence_id, event_type, actor_type, actor_id, actor_name, payload_json, created_at
+     ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), params.reminderId, params.occurrenceId ?? null, params.eventType, params.actorType, params.actorId ?? null, params.actorName ?? null, params.payload ? JSON.stringify(params.payload) : null, params.createdAt ?? Date.now());
+}
+function getReminderRowById(db, reminderId) {
+    const row = db.prepare(`SELECT reminder_id as reminderId,
+            agent_id as agentId,
+            target_user_id as targetUserId,
+            title,
+            prompt_text as promptText,
+            schedule_kind as scheduleKind,
+            interval_unit as intervalUnit,
+            interval_value as intervalValue,
+            start_at as startAt,
+            end_at as endAt,
+            max_occurrences as maxOccurrences,
+            status,
+            timezone,
+            last_scheduled_at as lastScheduledAt,
+            next_run_at as nextRunAt,
+            created_by_user_id as createdByUserId,
+            created_by_agent_id as createdByAgentId,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM agent_reminders
+      WHERE reminder_id = ?
+      LIMIT 1`).get(reminderId);
+    return row ?? null;
+}
+function getReminderOccurrenceRowById(db, occurrenceId) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId,
+            aro.scheduled_for as scheduledFor,
+            aro.started_at as startedAt,
+            aro.completed_at as completedAt,
+            aro.status,
+            aro.task_id as taskId,
+            aro.conversation_id as conversationId,
+            aro.thread_root_id as threadRootId,
+            aro.error,
+            aro.created_at as createdAt,
+            aro.updated_at as updatedAt,
+            t.task_number as taskNumber,
+            t.title as taskTitle,
+            t.status as taskStatus
+       FROM agent_reminder_occurrences aro
+       LEFT JOIN tasks t ON t.task_id = aro.task_id
+      WHERE aro.occurrence_id = ?
+      LIMIT 1`).get(occurrenceId);
+    return row ?? null;
+}
+function getLatestReminderOccurrenceRowByReminderId(db, reminderId) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId,
+            aro.scheduled_for as scheduledFor,
+            aro.started_at as startedAt,
+            aro.completed_at as completedAt,
+            aro.status,
+            aro.task_id as taskId,
+            aro.conversation_id as conversationId,
+            aro.thread_root_id as threadRootId,
+            aro.error,
+            aro.created_at as createdAt,
+            aro.updated_at as updatedAt,
+            t.task_number as taskNumber,
+            t.title as taskTitle,
+            t.status as taskStatus
+       FROM agent_reminder_occurrences aro
+       LEFT JOIN tasks t ON t.task_id = aro.task_id
+      WHERE aro.reminder_id = ?
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT 1`).get(reminderId);
+    return row ?? null;
+}
+function getCurrentReminderOccurrenceRowByReminderId(db, reminderId) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId,
+            aro.scheduled_for as scheduledFor,
+            aro.started_at as startedAt,
+            aro.completed_at as completedAt,
+            aro.status,
+            aro.task_id as taskId,
+            aro.conversation_id as conversationId,
+            aro.thread_root_id as threadRootId,
+            aro.error,
+            aro.created_at as createdAt,
+            aro.updated_at as updatedAt,
+            t.task_number as taskNumber,
+            t.title as taskTitle,
+            t.status as taskStatus
+       FROM agent_reminder_occurrences aro
+       LEFT JOIN tasks t ON t.task_id = aro.task_id
+      WHERE aro.reminder_id = ?
+        AND aro.status IN ('pending', 'dispatched', 'awaiting_review', 'failed', 'snoozed')
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT 1`).get(reminderId);
+    return row ?? null;
+}
+function hasReminderOccurrenceAtTime(db, reminderId, scheduledFor, excludeOccurrenceId) {
+    const row = excludeOccurrenceId
+        ? db.prepare(`SELECT 1 as found
+           FROM agent_reminder_occurrences
+          WHERE reminder_id = ?
+            AND scheduled_for = ?
+            AND occurrence_id != ?
+          LIMIT 1`).get(reminderId, scheduledFor, excludeOccurrenceId)
+        : db.prepare(`SELECT 1 as found
+           FROM agent_reminder_occurrences
+          WHERE reminder_id = ?
+            AND scheduled_for = ?
+          LIMIT 1`).get(reminderId, scheduledFor);
+    return !!row;
+}
+function allocateOccurrenceScheduledFor(db, reminderId, desiredScheduledFor, excludeOccurrenceId) {
+    let scheduledFor = Math.max(1, Math.floor(desiredScheduledFor));
+    while (hasReminderOccurrenceAtTime(db, reminderId, scheduledFor, excludeOccurrenceId)) {
+        scheduledFor += 1;
+    }
+    return scheduledFor;
+}
+function listRecentOccurrencesByReminderIds(db, reminderIds, limitPerReminder = 5) {
+    const uniqueReminderIds = [...new Set(reminderIds.filter(Boolean))];
+    const result = new Map();
+    if (uniqueReminderIds.length === 0)
+        return result;
+    const placeholders = uniqueReminderIds.map(() => '?').join(', ');
+    const rows = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId,
+            aro.scheduled_for as scheduledFor,
+            aro.started_at as startedAt,
+            aro.completed_at as completedAt,
+            aro.status,
+            aro.task_id as taskId,
+            aro.conversation_id as conversationId,
+            aro.thread_root_id as threadRootId,
+            aro.error,
+            aro.created_at as createdAt,
+            aro.updated_at as updatedAt,
+            t.task_number as taskNumber,
+            t.title as taskTitle,
+            t.status as taskStatus
+       FROM agent_reminder_occurrences aro
+       LEFT JOIN tasks t ON t.task_id = aro.task_id
+      WHERE aro.reminder_id IN (${placeholders})
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC`).all(...uniqueReminderIds);
+    for (const row of rows) {
+        const list = result.get(row.reminderId) ?? [];
+        if (list.length >= limitPerReminder)
+            continue;
+        list.push(mapOccurrenceRow(row));
+        result.set(row.reminderId, list);
+    }
+    return result;
+}
+function listReminderRowsForAgentUser(db, agentId, targetUserId) {
+    const rows = targetUserId == null
+        ? db.prepare(`SELECT reminder_id as reminderId,
+                agent_id as agentId,
+                target_user_id as targetUserId,
+                title,
+                prompt_text as promptText,
+                schedule_kind as scheduleKind,
+                interval_unit as intervalUnit,
+                interval_value as intervalValue,
+                start_at as startAt,
+                end_at as endAt,
+                max_occurrences as maxOccurrences,
+                status,
+                timezone,
+                last_scheduled_at as lastScheduledAt,
+                next_run_at as nextRunAt,
+                created_by_user_id as createdByUserId,
+                created_by_agent_id as createdByAgentId,
+                created_at as createdAt,
+                updated_at as updatedAt
+           FROM agent_reminders
+          WHERE agent_id = ?
+            AND target_user_id IS NULL
+          ORDER BY CASE status
+                     WHEN 'needs_attention' THEN 0
+                     WHEN 'awaiting_review' THEN 1
+                     WHEN 'in_progress' THEN 2
+                     WHEN 'active' THEN 3
+                     WHEN 'paused' THEN 4
+                     WHEN 'completed' THEN 5
+                     WHEN 'cancelled' THEN 6
+                     ELSE 7
+                   END,
+                   COALESCE(next_run_at, updated_at) ASC,
+                   updated_at DESC`).all(agentId)
+        : db.prepare(`SELECT reminder_id as reminderId,
+                agent_id as agentId,
+                target_user_id as targetUserId,
+                title,
+                prompt_text as promptText,
+                schedule_kind as scheduleKind,
+                interval_unit as intervalUnit,
+                interval_value as intervalValue,
+                start_at as startAt,
+                end_at as endAt,
+                max_occurrences as maxOccurrences,
+                status,
+                timezone,
+                last_scheduled_at as lastScheduledAt,
+                next_run_at as nextRunAt,
+                created_by_user_id as createdByUserId,
+                created_by_agent_id as createdByAgentId,
+                created_at as createdAt,
+                updated_at as updatedAt
+           FROM agent_reminders
+          WHERE agent_id = ?
+            AND target_user_id = ?
+          ORDER BY CASE status
+                     WHEN 'needs_attention' THEN 0
+                     WHEN 'awaiting_review' THEN 1
+                     WHEN 'in_progress' THEN 2
+                     WHEN 'active' THEN 3
+                     WHEN 'paused' THEN 4
+                     WHEN 'completed' THEN 5
+                     WHEN 'cancelled' THEN 6
+                     ELSE 7
+                   END,
+                   COALESCE(next_run_at, updated_at) ASC,
+                   updated_at DESC`).all(agentId, targetUserId);
+    return rows;
+}
+function findReminderRowForAgentUser(db, agentId, reminderId, targetUserId) {
+    const row = targetUserId == null
+        ? db.prepare(`SELECT reminder_id as reminderId,
+                agent_id as agentId,
+                target_user_id as targetUserId,
+                title,
+                prompt_text as promptText,
+                schedule_kind as scheduleKind,
+                interval_unit as intervalUnit,
+                interval_value as intervalValue,
+                start_at as startAt,
+                end_at as endAt,
+                max_occurrences as maxOccurrences,
+                status,
+                timezone,
+                last_scheduled_at as lastScheduledAt,
+                next_run_at as nextRunAt,
+                created_by_user_id as createdByUserId,
+                created_by_agent_id as createdByAgentId,
+                created_at as createdAt,
+                updated_at as updatedAt
+           FROM agent_reminders
+          WHERE reminder_id = ?
+            AND agent_id = ?
+            AND target_user_id IS NULL
+          LIMIT 1`).get(reminderId, agentId)
+        : db.prepare(`SELECT reminder_id as reminderId,
+                agent_id as agentId,
+                target_user_id as targetUserId,
+                title,
+                prompt_text as promptText,
+                schedule_kind as scheduleKind,
+                interval_unit as intervalUnit,
+                interval_value as intervalValue,
+                start_at as startAt,
+                end_at as endAt,
+                max_occurrences as maxOccurrences,
+                status,
+                timezone,
+                last_scheduled_at as lastScheduledAt,
+                next_run_at as nextRunAt,
+                created_by_user_id as createdByUserId,
+                created_by_agent_id as createdByAgentId,
+                created_at as createdAt,
+                updated_at as updatedAt
+           FROM agent_reminders
+          WHERE reminder_id = ?
+            AND agent_id = ?
+            AND target_user_id = ?
+          LIMIT 1`).get(reminderId, agentId, targetUserId);
+    return row ?? null;
+}
+function buildReminderInfoForRow(db, row) {
+    const recentOccurrences = listRecentOccurrencesByReminderIds(db, [row.reminderId]).get(row.reminderId) ?? [];
+    return mapReminderRow(row, recentOccurrences);
+}
+function buildReminderCurrentOccurrenceResult(db, reminderRow) {
+    const currentOccurrence = getCurrentReminderOccurrenceRowByReminderId(db, reminderRow.reminderId);
+    const latestOccurrence = currentOccurrence ?? getLatestReminderOccurrenceRowByReminderId(db, reminderRow.reminderId);
+    return {
+        reminder: buildReminderInfoForRow(db, reminderRow),
+        currentOccurrence: currentOccurrence ? mapOccurrenceRow(currentOccurrence) : null,
+        latestOccurrence: latestOccurrence ? mapOccurrenceRow(latestOccurrence) : null,
+    };
+}
+export function listAgentRemindersForUser(db, agentId, targetUserId) {
+    const rows = listReminderRowsForAgentUser(db, agentId, targetUserId);
+    const recentOccurrences = listRecentOccurrencesByReminderIds(db, rows.map((row) => row.reminderId));
+    return rows.map((row) => mapReminderRow(row, recentOccurrences.get(row.reminderId) ?? []));
+}
+export function getAgentReminderForUser(db, agentId, reminderId, targetUserId) {
+    const row = findReminderRowForAgentUser(db, agentId, reminderId, targetUserId);
+    return row ? buildReminderInfoForRow(db, row) : null;
+}
+export function listAgentReminderOccurrencesForUser(db, agentId, reminderId, targetUserId, limit = 50) {
+    const row = findReminderRowForAgentUser(db, agentId, reminderId, targetUserId);
+    if (!row)
+        return null;
+    const occurrences = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId,
+            aro.scheduled_for as scheduledFor,
+            aro.started_at as startedAt,
+            aro.completed_at as completedAt,
+            aro.status,
+            aro.task_id as taskId,
+            aro.conversation_id as conversationId,
+            aro.thread_root_id as threadRootId,
+            aro.error,
+            aro.created_at as createdAt,
+            aro.updated_at as updatedAt,
+            t.task_number as taskNumber,
+            t.title as taskTitle,
+            t.status as taskStatus
+       FROM agent_reminder_occurrences aro
+       LEFT JOIN tasks t ON t.task_id = aro.task_id
+      WHERE aro.reminder_id = ?
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT ?`).all(reminderId, limit);
+    return {
+        reminder: buildReminderInfoForRow(db, row),
+        occurrences: occurrences.map(mapOccurrenceRow),
+    };
+}
+export function getAgentReminderOccurrenceForUser(db, params) {
+    const occurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+    if (!occurrence)
+        return null;
+    const reminder = findReminderRowForAgentUser(db, params.agentId, occurrence.reminderId, params.targetUserId);
+    if (!reminder)
+        return null;
+    return {
+        reminder: buildReminderInfoForRow(db, reminder),
+        occurrence: mapOccurrenceRow(occurrence),
+    };
+}
+export function getAgentReminderCurrentOccurrenceForUser(db, params) {
+    const reminder = findReminderRowForAgentUser(db, params.agentId, params.reminderId, params.targetUserId);
+    if (!reminder)
+        return null;
+    return buildReminderCurrentOccurrenceResult(db, reminder);
+}
+export function createAgentReminder(db, params) {
+    const normalized = normalizeReminderUpsertInput(params.request);
+    const now = params.now ?? Date.now();
+    const reminderId = randomUUID();
+    const nextRunAt = computeNextRunAt({
+        scheduleKind: normalized.scheduleKind,
+        startAt: normalized.startAt,
+        intervalUnit: normalized.intervalUnit,
+        intervalValue: normalized.intervalValue,
+        endAt: normalized.endAt,
+        maxOccurrences: normalized.maxOccurrences,
+        lastScheduledAt: null,
+        existingOccurrenceCount: 0,
+        now,
+    });
+    const status = nextRunAt == null ? 'completed' : 'active';
+    db.prepare(`INSERT INTO agent_reminders(
+       reminder_id, agent_id, target_user_id, title, prompt_text, schedule_kind,
+       interval_unit, interval_value, start_at, end_at, max_occurrences, status,
+       timezone, last_scheduled_at, next_run_at, created_by_user_id, created_by_agent_id,
+       created_at, updated_at
+     ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?)`).run(reminderId, params.agentId, params.targetUserId, normalized.title, normalized.promptText, normalized.scheduleKind, normalized.intervalUnit, normalized.intervalValue, normalized.startAt, normalized.endAt, normalized.maxOccurrences, status, AGENT_REMINDER_TIMEZONE, nextRunAt, params.createdByUserId ?? null, params.createdByAgentId ?? null, now, now);
+    appendReminderEvent(db, {
+        reminderId,
+        eventType: 'created',
+        actorType: params.createdByAgentId ? 'agent' : 'user',
+        actorId: params.createdByAgentId ?? params.createdByUserId ?? null,
+        payload: {
+            title: normalized.title,
+            scheduleKind: normalized.scheduleKind,
+            nextRunAt,
+            status,
+        },
+        createdAt: now,
+    });
+    const row = getReminderRowById(db, reminderId);
+    if (!row)
+        throw new Error('Failed to create reminder');
+    return buildReminderInfoForRow(db, row);
+}
+export function updateAgentReminder(db, params) {
+    const existingRow = getReminderRowById(db, params.reminderId);
+    if (!existingRow)
+        return null;
+    if (existingRow.status === 'cancelled' || existingRow.status === 'completed') {
+        throw new Error(`Cannot update a ${existingRow.status} reminder`);
+    }
+    const existing = {
+        title: existingRow.title,
+        promptText: existingRow.promptText,
+        scheduleKind: existingRow.scheduleKind,
+        startAt: existingRow.startAt,
+        intervalUnit: existingRow.intervalUnit,
+        intervalValue: existingRow.intervalValue,
+        endAt: existingRow.endAt,
+        maxOccurrences: existingRow.maxOccurrences,
+    };
+    const normalized = normalizeReminderUpsertInput(params.request, existing);
+    assertOneTimeScheduleStillMutable(db, existingRow, normalized);
+    const now = params.now ?? Date.now();
+    const existingOccurrenceCount = countReminderOccurrences(db, params.reminderId);
+    const nextRunAt = existingRow.status === 'paused'
+        ? existingRow.nextRunAt
+        : computeNextRunAt({
+            scheduleKind: normalized.scheduleKind,
+            startAt: normalized.startAt,
+            intervalUnit: normalized.intervalUnit,
+            intervalValue: normalized.intervalValue,
+            endAt: normalized.endAt,
+            maxOccurrences: normalized.maxOccurrences,
+            lastScheduledAt: existingRow.lastScheduledAt,
+            existingOccurrenceCount,
+            now,
+        });
+    const openOccurrences = countOpenReminderOccurrences(db, params.reminderId);
+    const status = nextRunAt == null && openOccurrences === 0
+        ? 'completed'
+        : existingRow.status;
+    db.prepare(`UPDATE agent_reminders
+        SET title = ?,
+            prompt_text = ?,
+            schedule_kind = ?,
+            interval_unit = ?,
+            interval_value = ?,
+            start_at = ?,
+            end_at = ?,
+            max_occurrences = ?,
+            next_run_at = ?,
+            status = ?,
+            updated_at = ?
+      WHERE reminder_id = ?`).run(normalized.title, normalized.promptText, normalized.scheduleKind, normalized.intervalUnit, normalized.intervalValue, normalized.startAt, normalized.endAt, normalized.maxOccurrences, nextRunAt, status, now, params.reminderId);
+    appendReminderEvent(db, {
+        reminderId: params.reminderId,
+        eventType: 'updated',
+        actorType: params.actor.actorType,
+        actorId: params.actor.actorId ?? null,
+        actorName: params.actor.actorName ?? null,
+        payload: {
+            nextRunAt,
+            status,
+        },
+        createdAt: now,
+    });
+    const row = getReminderRowById(db, params.reminderId);
+    return row ? buildReminderInfoForRow(db, row) : null;
+}
+function transitionReminderStatus(db, reminderId, nextStatus, now, actor) {
+    const row = getReminderRowById(db, reminderId);
+    if (!row)
+        return null;
+    if (row.status === 'cancelled' || row.status === 'completed') {
+        throw new Error(`Cannot change a ${row.status} reminder`);
+    }
+    if (hasReminderTriggered(db, row)) {
+        if (nextStatus === 'paused' || nextStatus === 'active') {
+            throw new Error('One-time reminders cannot pause or resume after their first occurrence');
+        }
+        if (nextStatus === 'cancelled') {
+            throw new Error('Triggered one-time reminders must be abandoned instead of cancelled');
+        }
+    }
+    let updatedStatus = nextStatus;
+    let nextRunAt = row.nextRunAt;
+    if (nextStatus === 'paused') {
+        nextRunAt = null;
+    }
+    else if (nextStatus === 'active') {
+        nextRunAt = computeNextRunAt({
+            scheduleKind: row.scheduleKind,
+            startAt: row.startAt,
+            intervalUnit: row.intervalUnit,
+            intervalValue: row.intervalValue,
+            endAt: row.endAt,
+            maxOccurrences: row.maxOccurrences,
+            lastScheduledAt: row.lastScheduledAt,
+            existingOccurrenceCount: countReminderOccurrences(db, reminderId),
+            now,
+        });
+        if (nextRunAt == null && countOpenReminderOccurrences(db, reminderId) === 0) {
+            updatedStatus = 'completed';
+        }
+    }
+    else if (nextStatus === 'cancelled') {
+        nextRunAt = null;
+    }
+    db.prepare(`UPDATE agent_reminders
+        SET status = ?, next_run_at = ?, updated_at = ?
+      WHERE reminder_id = ?`).run(updatedStatus, nextRunAt, now, reminderId);
+    appendReminderEvent(db, {
+        reminderId,
+        eventType: updatedStatus === 'paused'
+            ? 'paused'
+            : updatedStatus === 'active'
+                ? 'resumed'
+                : 'cancelled',
+        actorType: actor.actorType,
+        actorId: actor.actorId ?? null,
+        actorName: actor.actorName ?? null,
+        payload: { nextRunAt, status: updatedStatus },
+        createdAt: now,
+    });
+    const updated = getReminderRowById(db, reminderId);
+    return updated ? buildReminderInfoForRow(db, updated) : null;
+}
+export function pauseAgentReminder(db, reminderId, actor) {
+    return transitionReminderStatus(db, reminderId, 'paused', Date.now(), actor);
+}
+export function resumeAgentReminder(db, reminderId, actor) {
+    return transitionReminderStatus(db, reminderId, 'active', Date.now(), actor);
+}
+export function cancelAgentReminder(db, reminderId, actor) {
+    return transitionReminderStatus(db, reminderId, 'cancelled', Date.now(), actor);
+}
+function maybeCompleteReminderAfterOccurrence(db, reminderId, now) {
+    const row = getReminderRowById(db, reminderId);
+    if (!row)
+        return;
+    if (row.status === 'cancelled' || row.status === 'completed')
+        return;
+    if (row.scheduleKind !== 'one_time' && row.status !== 'active')
+        return;
+    if (row.nextRunAt != null)
+        return;
+    if (countOpenReminderOccurrences(db, reminderId) > 0)
+        return;
+    db.prepare(`UPDATE agent_reminders
+        SET status = 'completed', updated_at = ?
+      WHERE reminder_id = ?`).run(now, reminderId);
+}
+export function runAgentReminderNowForUser(db, params) {
+    const reminder = findReminderRowForAgentUser(db, params.agentId, params.reminderId, params.targetUserId);
+    if (!reminder)
+        return null;
+    if (reminder.status === 'cancelled' || reminder.status === 'completed') {
+        throw new Error(`Cannot run a ${reminder.status} reminder`);
+    }
+    const currentOpenOccurrence = getCurrentReminderOccurrenceRowByReminderId(db, reminder.reminderId);
+    const retryableFailedOccurrence = reminder.scheduleKind === 'one_time' && isRetryableFailedOneTimeOccurrence(currentOpenOccurrence)
+        ? currentOpenOccurrence
+        : null;
+    if (reminder.scheduleKind === 'one_time' && hasReminderTriggered(db, reminder) && !retryableFailedOccurrence) {
+        throw new Error('One-time reminders cannot run again after their first occurrence');
+    }
+    if (countOpenReminderOccurrences(db, reminder.reminderId) > 0 && !retryableFailedOccurrence) {
+        throw new Error('Reminder already has an open occurrence');
+    }
+    const now = params.now ?? Date.now();
+    if (retryableFailedOccurrence) {
+        const scheduledFor = allocateOccurrenceScheduledFor(db, reminder.reminderId, now, retryableFailedOccurrence.occurrenceId);
+        db.transaction(() => {
+            db.prepare(`UPDATE agent_reminder_occurrences
+            SET status = 'pending',
+                scheduled_for = ?,
+                started_at = NULL,
+                completed_at = NULL,
+                error = NULL,
+                updated_at = ?
+          WHERE occurrence_id = ?`).run(scheduledFor, now, retryableFailedOccurrence.occurrenceId);
+            db.prepare(`UPDATE agent_reminders
+            SET status = 'in_progress',
+                updated_at = ?
+          WHERE reminder_id = ?`).run(now, reminder.reminderId);
+            appendReminderEvent(db, {
+                reminderId: reminder.reminderId,
+                occurrenceId: retryableFailedOccurrence.occurrenceId,
+                eventType: 'scheduled',
+                actorType: params.actor.actorType,
+                actorId: params.actor.actorId ?? null,
+                actorName: params.actor.actorName ?? null,
+                payload: {
+                    scheduledFor,
+                    kind: 'run_now_retry',
+                },
+                createdAt: now,
+            });
+        })();
+        const updatedReminder = getReminderRowById(db, reminder.reminderId);
+        const updatedOccurrence = getReminderOccurrenceRowById(db, retryableFailedOccurrence.occurrenceId);
+        if (!updatedReminder || !updatedOccurrence) {
+            throw new Error('Failed to retry reminder occurrence');
+        }
+        return {
+            reminder: buildReminderInfoForRow(db, updatedReminder),
+            occurrence: mapOccurrenceRow(updatedOccurrence),
+        };
+    }
+    const occurrenceId = randomUUID();
+    const scheduledFor = allocateOccurrenceScheduledFor(db, reminder.reminderId, now);
+    const consumesOneTimeSlot = reminder.scheduleKind === 'one_time'
+        && reminder.lastScheduledAt == null
+        && countReminderOccurrences(db, reminder.reminderId) === 0;
+    db.transaction(() => {
+        db.prepare(`INSERT INTO agent_reminder_occurrences(
+         occurrence_id, reminder_id, scheduled_for, trigger_kind, status, created_at, updated_at
+       ) VALUES(?, ?, ?, ?, 'pending', ?, ?)`).run(occurrenceId, reminder.reminderId, scheduledFor, consumesOneTimeSlot ? 'scheduled' : 'manual_run_now', now, now);
+        db.prepare(`UPDATE agent_reminders
+          SET status = CASE WHEN schedule_kind = 'one_time' THEN 'in_progress' ELSE status END,
+              last_scheduled_at = CASE WHEN ? THEN ? ELSE last_scheduled_at END,
+              next_run_at = CASE WHEN ? THEN NULL ELSE next_run_at END,
+              updated_at = ?
+        WHERE reminder_id = ?`).run(consumesOneTimeSlot ? 1 : 0, scheduledFor, consumesOneTimeSlot ? 1 : 0, now, reminder.reminderId);
+        appendReminderEvent(db, {
+            reminderId: reminder.reminderId,
+            occurrenceId,
+            eventType: 'scheduled',
+            actorType: params.actor.actorType,
+            actorId: params.actor.actorId ?? null,
+            actorName: params.actor.actorName ?? null,
+            payload: {
+                scheduledFor,
+                kind: 'run_now',
+            },
+            createdAt: now,
+        });
+    })();
+    const updatedReminder = getReminderRowById(db, reminder.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, occurrenceId);
+    if (!updatedReminder || !updatedOccurrence) {
+        throw new Error('Failed to create reminder occurrence');
+    }
+    return {
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+    };
+}
+export function skipAgentReminderOccurrenceForUser(db, params) {
+    const scoped = getAgentReminderOccurrenceForUser(db, {
+        agentId: params.agentId,
+        occurrenceId: params.occurrenceId,
+        targetUserId: params.targetUserId,
+    });
+    if (!scoped)
+        return null;
+    ensureOneTimeFollowUpActionAllowed(scoped.reminder, 'skip');
+    if (!isOpenReminderOccurrenceStatus(scoped.occurrence.status)) {
+        throw new Error('Only open reminder occurrences can be skipped');
+    }
+    if (scoped.occurrence.status === 'dispatched'
+        && (scoped.occurrence.conversationId || scoped.occurrence.taskId || scoped.occurrence.threadRootId)) {
+        if (!scoped.occurrence.conversationId || !params.cancelActiveRun) {
+            throw new Error('Cannot skip a dispatched reminder occurrence without task-thread cancellation support');
+        }
+        params.cancelActiveRun(scoped.occurrence.conversationId);
+    }
+    const now = params.now ?? Date.now();
+    db.transaction(() => {
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = 'skipped',
+              completed_at = COALESCE(completed_at, ?),
+              updated_at = ?
+        WHERE occurrence_id = ?`).run(now, now, params.occurrenceId);
+        appendReminderEvent(db, {
+            reminderId: scoped.reminder.reminderId,
+            occurrenceId: params.occurrenceId,
+            eventType: 'skipped',
+            actorType: params.actor.actorType,
+            actorId: params.actor.actorId ?? null,
+            actorName: params.actor.actorName ?? null,
+            payload: params.reason ? { reason: params.reason } : null,
+            createdAt: now,
+        });
+        maybeCompleteReminderAfterOccurrence(db, scoped.reminder.reminderId, now);
+    })();
+    const updatedReminder = getReminderRowById(db, scoped.reminder.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: null,
+    };
+}
+export function snoozeAgentReminderOccurrenceForUser(db, params) {
+    const scoped = getAgentReminderOccurrenceForUser(db, {
+        agentId: params.agentId,
+        occurrenceId: params.occurrenceId,
+        targetUserId: params.targetUserId,
+    });
+    if (!scoped)
+        return null;
+    ensureOneTimeFollowUpActionAllowed(scoped.reminder, 'snooze');
+    if (!isOpenReminderOccurrenceStatus(scoped.occurrence.status)) {
+        throw new Error('Only open reminder occurrences can be snoozed');
+    }
+    if (scoped.occurrence.status === 'dispatched'
+        && (scoped.occurrence.conversationId || scoped.occurrence.taskId || scoped.occurrence.threadRootId)) {
+        if (!scoped.occurrence.conversationId || !params.cancelActiveRun) {
+            throw new Error('Cannot snooze a dispatched reminder occurrence without task-thread cancellation support');
+        }
+        params.cancelActiveRun(scoped.occurrence.conversationId);
+    }
+    const now = params.now ?? Date.now();
+    const until = normalizeNullableTimestamp(params.until);
+    if (!until || until <= now) {
+        throw new Error('until must be a future timestamp');
+    }
+    const scheduledFor = allocateOccurrenceScheduledFor(db, scoped.reminder.reminderId, until, params.occurrenceId);
+    db.transaction(() => {
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = 'snoozed',
+              scheduled_for = ?,
+              error = NULL,
+              updated_at = ?
+        WHERE occurrence_id = ?`).run(scheduledFor, now, params.occurrenceId);
+        appendReminderEvent(db, {
+            reminderId: scoped.reminder.reminderId,
+            occurrenceId: params.occurrenceId,
+            eventType: 'snoozed',
+            actorType: params.actor.actorType,
+            actorId: params.actor.actorId ?? null,
+            actorName: params.actor.actorName ?? null,
+            payload: {
+                until: scheduledFor,
+            },
+            createdAt: now,
+        });
+        db.prepare(`UPDATE agent_reminders
+          SET updated_at = ?
+        WHERE reminder_id = ?`).run(now, scoped.reminder.reminderId);
+    })();
+    const updatedReminder = getReminderRowById(db, scoped.reminder.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: null,
+    };
+}
+export function completeAgentReminderOccurrence(db, params) {
+    const occurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+    if (!occurrence)
+        return null;
+    const reminder = getReminderRowById(db, occurrence.reminderId);
+    if (!reminder)
+        return null;
+    ensureOneTimeOccurrenceSupportsReview(reminder);
+    if (occurrence.status !== 'completed' && !isOpenReminderOccurrenceStatus(occurrence.status)) {
+        throw new Error('Only open reminder occurrences can be completed');
+    }
+    const now = params.now ?? Date.now();
+    let taskResult = null;
+    if (occurrence.status !== 'completed' && occurrence.taskId && params.ensureTaskDone) {
+        taskResult = params.ensureTaskDone(occurrence.taskId);
+    }
+    else if (occurrence.taskId && occurrence.taskNumber != null) {
+        taskResult = {
+            taskId: occurrence.taskId,
+            status: 'done',
+            taskNumber: occurrence.taskNumber,
+        };
+    }
+    if (occurrence.status !== 'completed') {
+        db.transaction(() => {
+            db.prepare(`UPDATE agent_reminder_occurrences
+            SET status = 'completed',
+                completed_at = COALESCE(completed_at, ?),
+                updated_at = ?
+          WHERE occurrence_id = ?`).run(now, now, params.occurrenceId);
+            appendReminderEvent(db, {
+                reminderId: occurrence.reminderId,
+                occurrenceId: occurrence.occurrenceId,
+                eventType: 'completed',
+                actorType: params.actor.actorType,
+                actorId: params.actor.actorId ?? null,
+                actorName: params.actor.actorName ?? null,
+                payload: taskResult ? { taskId: taskResult.taskId, taskNumber: taskResult.taskNumber } : null,
+                createdAt: now,
+            });
+            if (taskResult) {
+                appendReminderEvent(db, {
+                    reminderId: occurrence.reminderId,
+                    occurrenceId: occurrence.occurrenceId,
+                    eventType: 'completed_task_marked_done',
+                    actorType: params.actor.actorType,
+                    actorId: params.actor.actorId ?? null,
+                    actorName: params.actor.actorName ?? null,
+                    payload: {
+                        taskId: taskResult.taskId,
+                        taskNumber: taskResult.taskNumber,
+                        status: taskResult.status,
+                    },
+                    createdAt: now,
+                });
+            }
+            maybeCompleteReminderAfterOccurrence(db, occurrence.reminderId, now);
+        })();
+    }
+    const updatedReminder = getReminderRowById(db, occurrence.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: taskResult,
+    };
+}
+export function submitAgentReminderOccurrenceForReview(db, params) {
+    const occurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+    if (!occurrence)
+        return null;
+    const reminder = getReminderRowById(db, occurrence.reminderId);
+    if (!reminder)
+        return null;
+    if (reminder.scheduleKind !== 'one_time') {
+        throw new Error('bigbang reminder submit-for-review is only valid for one-time reminders');
+    }
+    const allowedStatuses = params.allowFailedLinkedOccurrence
+        ? ['dispatched', 'failed']
+        : ['dispatched'];
+    if (!allowedStatuses.includes(occurrence.status)) {
+        throw new Error('Only dispatched one-time reminder occurrences can be submitted for review');
+    }
+    if (!occurrence.taskId) {
+        throw new Error('One-time reminder occurrences need a linked task before they can be submitted for review');
+    }
+    const now = params.now ?? Date.now();
+    let taskResult = null;
+    if (params.ensureTaskInReview) {
+        taskResult = params.ensureTaskInReview(occurrence.taskId);
+    }
+    else if (occurrence.taskNumber != null && occurrence.taskStatus === 'in_review') {
+        taskResult = {
+            taskId: occurrence.taskId,
+            status: 'in_review',
+            taskNumber: occurrence.taskNumber,
+        };
+    }
+    if (!taskResult) {
+        throw new Error('One-time reminder occurrences must move their linked task into in_review before submission');
+    }
+    db.transaction(() => {
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = 'awaiting_review',
+              error = NULL,
+              updated_at = ?
+        WHERE occurrence_id = ?`).run(now, params.occurrenceId);
+        db.prepare(`UPDATE agent_reminders
+          SET status = 'awaiting_review',
+              updated_at = ?
+        WHERE reminder_id = ?`).run(now, reminder.reminderId);
+        appendReminderEvent(db, {
+            reminderId: reminder.reminderId,
+            occurrenceId: occurrence.occurrenceId,
+            eventType: 'submitted_for_review',
+            actorType: params.actor.actorType,
+            actorId: params.actor.actorId ?? null,
+            actorName: params.actor.actorName ?? null,
+            payload: taskResult ? { taskId: taskResult.taskId, taskNumber: taskResult.taskNumber } : null,
+            createdAt: now,
+        });
+        if (taskResult) {
+            appendReminderEvent(db, {
+                reminderId: reminder.reminderId,
+                occurrenceId: occurrence.occurrenceId,
+                eventType: 'submitted_task_marked_in_review',
+                actorType: params.actor.actorType,
+                actorId: params.actor.actorId ?? null,
+                actorName: params.actor.actorName ?? null,
+                payload: {
+                    taskId: taskResult.taskId,
+                    taskNumber: taskResult.taskNumber,
+                    status: taskResult.status,
+                },
+                createdAt: now,
+            });
+        }
+    })();
+    const updatedReminder = getReminderRowById(db, reminder.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, occurrence.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: taskResult,
+    };
+}
+export function completeCurrentReminderOccurrenceForUser(db, params) {
+    const reminder = findReminderRowForAgentUser(db, params.agentId, params.reminderId, params.targetUserId);
+    if (!reminder)
+        return null;
+    const occurrence = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId,
+            aro.scheduled_for as scheduledFor,
+            aro.started_at as startedAt,
+            aro.completed_at as completedAt,
+            aro.status,
+            aro.task_id as taskId,
+            aro.conversation_id as conversationId,
+            aro.thread_root_id as threadRootId,
+            aro.error,
+            aro.created_at as createdAt,
+            aro.updated_at as updatedAt,
+            t.task_number as taskNumber,
+            t.title as taskTitle,
+            t.status as taskStatus
+       FROM agent_reminder_occurrences aro
+      LEFT JOIN tasks t ON t.task_id = aro.task_id
+      WHERE aro.reminder_id = ?
+        AND aro.status IN ('pending', 'dispatched', 'awaiting_review', 'failed', 'snoozed')
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT 1`).get(params.reminderId);
+    if (!occurrence)
+        return null;
+    return completeAgentReminderOccurrence(db, {
+        occurrenceId: occurrence.occurrenceId,
+        now: params.now,
+        actor: params.actor,
+        ensureTaskDone: params.ensureTaskDone,
+    });
+}
+export function submitCurrentReminderOccurrenceForReviewForUser(db, params) {
+    const reminder = findReminderRowForAgentUser(db, params.agentId, params.reminderId, params.targetUserId);
+    if (!reminder)
+        return null;
+    const occurrence = getCurrentReminderOccurrenceRowByReminderId(db, params.reminderId);
+    if (!occurrence)
+        return null;
+    return submitAgentReminderOccurrenceForReview(db, {
+        occurrenceId: occurrence.occurrenceId,
+        now: params.now,
+        actor: params.actor,
+        ensureTaskInReview: params.ensureTaskInReview,
+    });
+}
+export function syncReminderOccurrenceForTaskInReview(db, params) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId
+       FROM agent_reminder_occurrences aro
+       INNER JOIN agent_reminders ar
+          ON ar.reminder_id = aro.reminder_id
+      WHERE aro.task_id = ?
+        AND aro.status IN ('dispatched', 'failed')
+        AND ar.schedule_kind = 'one_time'
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT 1`).get(params.taskId);
+    if (!row)
+        return null;
+    return submitAgentReminderOccurrenceForReview(db, {
+        occurrenceId: row.occurrenceId,
+        now: params.now,
+        actor: params.actor,
+        allowFailedLinkedOccurrence: true,
+    });
+}
+export function autoCompleteReminderOccurrenceForTaskDone(db, params) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId
+       FROM agent_reminder_occurrences aro
+      WHERE aro.task_id = ?
+        AND aro.status IN ('pending', 'dispatched', 'awaiting_review', 'failed')
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT 1`).get(params.taskId);
+    if (!row)
+        return null;
+    const occurrence = getReminderOccurrenceRowById(db, row.occurrenceId);
+    if (!occurrence)
+        return null;
+    const reminder = getReminderRowById(db, occurrence.reminderId);
+    if (!reminder)
+        return null;
+    const now = params.now ?? Date.now();
+    if (occurrence.status !== 'completed') {
+        db.transaction(() => {
+            db.prepare(`UPDATE agent_reminder_occurrences
+            SET status = 'completed',
+                completed_at = COALESCE(completed_at, ?),
+                updated_at = ?
+          WHERE occurrence_id = ?`).run(now, now, occurrence.occurrenceId);
+            if (reminder.scheduleKind === 'one_time') {
+                db.prepare(`UPDATE agent_reminders
+              SET status = 'completed',
+                  updated_at = ?
+            WHERE reminder_id = ?`).run(now, occurrence.reminderId);
+            }
+            appendReminderEvent(db, {
+                reminderId: occurrence.reminderId,
+                occurrenceId: occurrence.occurrenceId,
+                eventType: 'auto_completed_from_task_done',
+                actorType: 'system',
+                actorName: 'system',
+                payload: { taskId: params.taskId },
+                createdAt: now,
+            });
+            maybeCompleteReminderAfterOccurrence(db, occurrence.reminderId, now);
+        })();
+    }
+    const updatedReminder = getReminderRowById(db, occurrence.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, occurrence.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: occurrence.taskId && occurrence.taskNumber != null
+            ? { taskId: occurrence.taskId, status: 'done', taskNumber: occurrence.taskNumber }
+            : null,
+    };
+}
+export function reopenReminderOccurrenceForTaskInProgress(db, params) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId
+       FROM agent_reminder_occurrences aro
+       INNER JOIN agent_reminders ar
+          ON ar.reminder_id = aro.reminder_id
+      WHERE aro.task_id = ?
+        AND aro.status = 'awaiting_review'
+        AND ar.schedule_kind = 'one_time'
+      ORDER BY aro.scheduled_for DESC, aro.created_at DESC
+      LIMIT 1`).get(params.taskId);
+    if (!row)
+        return null;
+    const occurrence = getReminderOccurrenceRowById(db, row.occurrenceId);
+    if (!occurrence)
+        return null;
+    const reminder = getReminderRowById(db, occurrence.reminderId);
+    if (!reminder)
+        return null;
+    const now = params.now ?? Date.now();
+    db.transaction(() => {
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = 'dispatched',
+              completed_at = NULL,
+              updated_at = ?
+        WHERE occurrence_id = ?`).run(now, occurrence.occurrenceId);
+        db.prepare(`UPDATE agent_reminders
+          SET status = 'in_progress',
+              updated_at = ?
+        WHERE reminder_id = ?`).run(now, occurrence.reminderId);
+        appendReminderEvent(db, {
+            reminderId: occurrence.reminderId,
+            occurrenceId: occurrence.occurrenceId,
+            eventType: 'reopened_for_rework',
+            actorType: 'system',
+            actorName: 'system',
+            payload: { taskId: params.taskId },
+            createdAt: now,
+        });
+    })();
+    const updatedReminder = getReminderRowById(db, occurrence.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, occurrence.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: occurrence.taskId && occurrence.taskNumber != null
+            ? { taskId: occurrence.taskId, status: 'in_progress', taskNumber: occurrence.taskNumber }
+            : null,
+    };
+}
+export function abandonOneTimeReminderForUser(db, params) {
+    const scopedReminder = findReminderRowForAgentUser(db, params.agentId, params.reminderId, params.targetUserId);
+    if (!scopedReminder)
+        return null;
+    if (scopedReminder.scheduleKind !== 'one_time' || !hasReminderTriggered(db, scopedReminder)) {
+        throw new Error('Only triggered one-time reminders can be abandoned');
+    }
+    const occurrence = getCurrentReminderOccurrenceRowByReminderId(db, scopedReminder.reminderId);
+    if (!occurrence) {
+        throw new Error('Triggered one-time reminder has no open occurrence to abandon');
+    }
+    if (occurrence.status === 'dispatched' && occurrence.conversationId && params.cancelActiveRun) {
+        params.cancelActiveRun(occurrence.conversationId);
+    }
+    const now = params.now ?? Date.now();
+    const taskResult = occurrence.taskId && params.closeLinkedTaskThread
+        ? params.closeLinkedTaskThread(occurrence.taskId)
+        : occurrence.taskId && occurrence.taskNumber != null && occurrence.taskStatus != null
+            ? { taskId: occurrence.taskId, status: occurrence.taskStatus, taskNumber: occurrence.taskNumber }
+            : null;
+    db.transaction(() => {
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = 'skipped',
+              completed_at = COALESCE(completed_at, ?),
+              updated_at = ?
+        WHERE occurrence_id = ?`).run(now, now, occurrence.occurrenceId);
+        db.prepare(`UPDATE agent_reminders
+          SET status = 'cancelled',
+              next_run_at = NULL,
+              updated_at = ?
+        WHERE reminder_id = ?`).run(now, scopedReminder.reminderId);
+        appendReminderEvent(db, {
+            reminderId: scopedReminder.reminderId,
+            occurrenceId: occurrence.occurrenceId,
+            eventType: 'abandoned',
+            actorType: params.actor.actorType,
+            actorId: params.actor.actorId ?? null,
+            actorName: params.actor.actorName ?? null,
+            payload: taskResult ? { taskId: taskResult.taskId, taskNumber: taskResult.taskNumber } : null,
+            createdAt: now,
+        });
+    })();
+    const updatedReminder = getReminderRowById(db, scopedReminder.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, occurrence.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: taskResult,
+    };
+}
+function scheduleDueReminderOccurrence(db, reminderId, now) {
+    const scheduled = db.transaction(() => {
+        const row = getReminderRowById(db, reminderId);
+        if (!row)
+            return null;
+        if (row.status !== 'active' || row.nextRunAt == null || row.nextRunAt > now)
+            return null;
+        const scheduledFor = row.nextRunAt;
+        const occurrenceCount = countReminderOccurrences(db, reminderId);
+        const nextRunAt = computeNextRunAt({
+            scheduleKind: row.scheduleKind,
+            startAt: row.startAt,
+            intervalUnit: row.intervalUnit,
+            intervalValue: row.intervalValue,
+            endAt: row.endAt,
+            maxOccurrences: row.maxOccurrences,
+            lastScheduledAt: scheduledFor,
+            existingOccurrenceCount: occurrenceCount + 1,
+            now,
+        });
+        const currentOpenOccurrence = getCurrentReminderOccurrenceRowByReminderId(db, reminderId);
+        if (currentOpenOccurrence) {
+            const blockedNextRunAt = computeNextRunAt({
+                scheduleKind: row.scheduleKind,
+                startAt: row.startAt,
+                intervalUnit: row.intervalUnit,
+                intervalValue: row.intervalValue,
+                endAt: row.endAt,
+                maxOccurrences: row.maxOccurrences,
+                lastScheduledAt: scheduledFor,
+                existingOccurrenceCount: occurrenceCount,
+                now,
+            });
+            db.prepare(`UPDATE agent_reminders
+            SET last_scheduled_at = ?,
+                next_run_at = ?,
+                status = CASE WHEN schedule_kind = 'one_time' THEN 'in_progress' ELSE status END,
+                updated_at = ?
+          WHERE reminder_id = ?`).run(scheduledFor, blockedNextRunAt, now, reminderId);
+            appendReminderEvent(db, {
+                reminderId,
+                occurrenceId: currentOpenOccurrence.occurrenceId,
+                eventType: 'blocked_by_open_occurrence',
+                actorType: 'system',
+                actorName: 'system',
+                payload: {
+                    scheduledFor,
+                    nextRunAt: blockedNextRunAt,
+                    blockingOccurrenceId: currentOpenOccurrence.occurrenceId,
+                    blockingStatus: currentOpenOccurrence.status,
+                },
+                createdAt: now,
+            });
+            return null;
+        }
+        const occurrenceId = randomUUID();
+        db.prepare(`INSERT INTO agent_reminder_occurrences(
+         occurrence_id, reminder_id, scheduled_for, trigger_kind, status, created_at, updated_at
+       ) VALUES(?, ?, ?, 'scheduled', 'pending', ?, ?)`).run(occurrenceId, reminderId, scheduledFor, now, now);
+        db.prepare(`UPDATE agent_reminders
+          SET last_scheduled_at = ?,
+              next_run_at = ?,
+              status = CASE WHEN schedule_kind = 'one_time' THEN 'in_progress' ELSE status END,
+              updated_at = ?
+        WHERE reminder_id = ?`).run(scheduledFor, nextRunAt, now, reminderId);
+        appendReminderEvent(db, {
+            reminderId,
+            occurrenceId,
+            eventType: 'scheduled',
+            actorType: 'system',
+            actorName: 'system',
+            payload: {
+                scheduledFor,
+                nextRunAt,
+            },
+            createdAt: now,
+        });
+        const reminderAfter = getReminderRowById(db, reminderId);
+        const occurrenceAfter = getReminderOccurrenceRowById(db, occurrenceId);
+        if (!reminderAfter || !occurrenceAfter)
+            return null;
+        return {
+            reminder: buildReminderInfoForRow(db, reminderAfter),
+            occurrence: mapOccurrenceRow(occurrenceAfter),
+        };
+    })();
+    return scheduled;
+}
+export function markAgentReminderDispatchOutcome(db, params) {
+    db.transaction(() => {
+        const reminder = getReminderRowById(db, params.reminderId);
+        const occurrence = getReminderOccurrenceRowById(db, params.occurrenceId);
+        if (!occurrence)
+            return;
+        const dispatchOutcomeSuperseded = reminder?.status === 'cancelled'
+            || reminder?.status === 'completed'
+            || reminder?.status === 'awaiting_review'
+            || occurrence.status === 'skipped'
+            || occurrence.status === 'completed'
+            || occurrence.status === 'awaiting_review';
+        if (dispatchOutcomeSuperseded) {
+            db.prepare(`UPDATE agent_reminder_occurrences
+            SET started_at = COALESCE(started_at, ?),
+                task_id = COALESCE(task_id, ?),
+                conversation_id = COALESCE(conversation_id, ?),
+                thread_root_id = COALESCE(thread_root_id, ?),
+                updated_at = ?
+          WHERE occurrence_id = ?`).run(params.now, params.result.taskId ?? null, params.result.conversationId ?? null, params.result.threadRootId ?? null, params.now, params.occurrenceId);
+            return;
+        }
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = ?,
+              started_at = COALESCE(started_at, ?),
+              task_id = COALESCE(?, task_id),
+              conversation_id = COALESCE(?, conversation_id),
+              thread_root_id = COALESCE(?, thread_root_id),
+              error = ?,
+              updated_at = ?
+        WHERE occurrence_id = ?`).run(params.result.status, params.now, params.result.taskId ?? null, params.result.conversationId ?? null, params.result.threadRootId ?? null, params.result.error ?? null, params.now, params.occurrenceId);
+        if (reminder?.scheduleKind === 'one_time') {
+            const reminderStatus = params.result.status === 'failed'
+                ? 'needs_attention'
+                : 'in_progress';
+            db.prepare(`UPDATE agent_reminders
+            SET status = ?,
+                updated_at = ?
+          WHERE reminder_id = ?`).run(reminderStatus, params.now, params.reminderId);
+        }
+        appendReminderEvent(db, {
+            reminderId: params.reminderId,
+            occurrenceId: params.occurrenceId,
+            eventType: params.result.status === 'dispatched'
+                ? 'dispatched'
+                : params.result.status === 'failed'
+                    ? 'failed'
+                    : 'skipped',
+            actorType: 'system',
+            actorName: 'system',
+            payload: {
+                taskId: params.result.taskId ?? null,
+                conversationId: params.result.conversationId ?? null,
+                threadRootId: params.result.threadRootId ?? null,
+                error: params.result.error ?? null,
+            },
+            createdAt: params.now,
+        });
+    })();
+}
+export function markReminderOccurrenceFailedForConversation(db, params) {
+    const row = db.prepare(`SELECT aro.occurrence_id as occurrenceId
+       FROM agent_reminder_occurrences aro
+       INNER JOIN agent_reminders ar
+          ON ar.reminder_id = aro.reminder_id
+      WHERE aro.conversation_id = ?
+        AND aro.status = 'dispatched'
+      ORDER BY CASE ar.schedule_kind
+                 WHEN 'one_time' THEN 0
+                 ELSE 1
+               END,
+               aro.scheduled_for DESC,
+               aro.created_at DESC
+      LIMIT 1`).get(params.conversationId);
+    if (!row)
+        return null;
+    const occurrence = getReminderOccurrenceRowById(db, row.occurrenceId);
+    if (!occurrence || occurrence.status !== 'dispatched')
+        return null;
+    const reminder = getReminderRowById(db, occurrence.reminderId);
+    if (!reminder)
+        return null;
+    const now = params.now ?? Date.now();
+    db.transaction(() => {
+        db.prepare(`UPDATE agent_reminder_occurrences
+          SET status = 'failed',
+              error = ?,
+              updated_at = ?
+        WHERE occurrence_id = ?
+          AND status = 'dispatched'`).run(params.error, now, occurrence.occurrenceId);
+        if (reminder.scheduleKind === 'one_time') {
+            db.prepare(`UPDATE agent_reminders
+            SET status = 'needs_attention',
+                updated_at = ?
+          WHERE reminder_id = ?
+            AND status NOT IN ('cancelled', 'completed', 'awaiting_review')`).run(now, reminder.reminderId);
+        }
+        appendReminderEvent(db, {
+            reminderId: reminder.reminderId,
+            occurrenceId: occurrence.occurrenceId,
+            eventType: 'failed',
+            actorType: 'system',
+            actorName: 'system',
+            payload: {
+                conversationId: params.conversationId,
+                error: params.error,
+                source: 'conversation_runtime',
+            },
+            createdAt: now,
+        });
+    })();
+    const updatedReminder = getReminderRowById(db, reminder.reminderId);
+    const updatedOccurrence = getReminderOccurrenceRowById(db, occurrence.occurrenceId);
+    if (!updatedReminder || !updatedOccurrence)
+        return null;
+    return {
+        ok: true,
+        reminder: buildReminderInfoForRow(db, updatedReminder),
+        occurrence: mapOccurrenceRow(updatedOccurrence),
+        task: updatedOccurrence.taskId && updatedOccurrence.taskNumber != null && updatedOccurrence.taskStatus != null
+            ? {
+                taskId: updatedOccurrence.taskId,
+                status: updatedOccurrence.taskStatus,
+                taskNumber: updatedOccurrence.taskNumber,
+            }
+            : null,
+    };
+}
+function listDueSnoozedOccurrences(db, now, limit) {
+    const rows = db.prepare(`SELECT aro.occurrence_id as occurrenceId,
+            aro.reminder_id as reminderId
+       FROM agent_reminder_occurrences aro
+       INNER JOIN agent_reminders ar
+          ON ar.reminder_id = aro.reminder_id
+      WHERE aro.status = 'snoozed'
+        AND aro.scheduled_for <= ?
+        AND ar.status = 'active'
+      ORDER BY aro.scheduled_for ASC, aro.created_at ASC
+      LIMIT ?`).all(now, limit);
+    const due = [];
+    for (const row of rows) {
+        const reminder = getReminderRowById(db, row.reminderId);
+        const occurrence = getReminderOccurrenceRowById(db, row.occurrenceId);
+        if (!reminder || !occurrence)
+            continue;
+        if (occurrence.status !== 'snoozed' || occurrence.scheduledFor > now)
+            continue;
+        due.push({
+            reminder: buildReminderInfoForRow(db, reminder),
+            occurrence: mapOccurrenceRow(occurrence),
+        });
+    }
+    return due;
+}
+export async function processDueAgentReminders(params) {
+    void params.conversationManager;
+    const now = params.now ?? Date.now();
+    const limit = Math.max(1, params.limit ?? 25);
+    const dueSnoozedOccurrences = listDueSnoozedOccurrences(params.db, now, limit);
+    for (const due of dueSnoozedOccurrences) {
+        let result;
+        try {
+            result = await params.onDispatchOccurrence(due);
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                status: 'failed',
+                error: String(error?.message ?? error),
+            };
+        }
+        markAgentReminderDispatchOutcome(params.db, {
+            occurrenceId: due.occurrence.occurrenceId,
+            reminderId: due.reminder.reminderId,
+            result,
+            now,
+        });
+    }
+    const dueRows = params.db.prepare(`SELECT reminder_id as reminderId
+       FROM agent_reminders
+      WHERE status = 'active'
+        AND next_run_at IS NOT NULL
+        AND next_run_at <= ?
+      ORDER BY next_run_at ASC
+      LIMIT ?`).all(now, limit);
+    for (const row of dueRows) {
+        const scheduled = scheduleDueReminderOccurrence(params.db, row.reminderId, now);
+        if (!scheduled)
+            continue;
+        let result;
+        try {
+            result = await params.onDispatchOccurrence(scheduled);
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                status: 'failed',
+                error: String(error?.message ?? error),
+            };
+        }
+        markAgentReminderDispatchOutcome(params.db, {
+            occurrenceId: scheduled.occurrence.occurrenceId,
+            reminderId: scheduled.reminder.reminderId,
+            result,
+            now,
+        });
+    }
+}
+export function startAgentReminderService(params) {
+    const intervalMs = Math.max(1_000, params.intervalMs ?? AGENT_REMINDER_POLL_INTERVAL_MS);
+    let closed = false;
+    let running = false;
+    let timer = null;
+    const tick = async () => {
+        if (closed || running)
+            return;
+        running = true;
+        try {
+            await processDueAgentReminders({
+                db: params.db,
+                conversationManager: params.conversationManager,
+                onDispatchOccurrence: params.onDispatchOccurrence,
+            });
+        }
+        finally {
+            running = false;
+        }
+    };
+    timer = setInterval(() => {
+        void tick();
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        tick,
+        stop: () => {
+            closed = true;
+            if (!timer)
+                return;
+            clearInterval(timer);
+            timer = null;
+        },
+    };
+}