@holon-run/agentinbox 0.2.0 → 0.4.0

package/dist/src/service.js

@@ -7,6 +7,7 @@ const source_schema_1 = require("./source_schema");
 const source_resolution_1 = require("./source_resolution");
 const filter_1 = require("./filter");
 const terminal_1 = require("./terminal");
+const runtime_gate_1 = require("./runtime_gate");
 const DEFAULT_SUBSCRIPTION_POLL_LIMIT = 100;
 const DEFAULT_ACTIVATION_WINDOW_MS = 3_000;
 const DEFAULT_ACTIVATION_MAX_ITEMS = 20;
@@ -17,6 +18,12 @@ const DEFAULT_OFFLINE_AGENT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const DEFAULT_GC_INTERVAL_MS = 60 * 1000;
 const DEFAULT_SYNC_INTERVAL_MS = 2_000;
 const DEFAULT_IDLE_SOURCE_GRACE_MS = 5 * 60 * 1000;
+const DIRECT_INBOX_SOURCE_ID = "__agentinbox_direct_text__";
+const DIRECT_INBOX_EVENT_VARIANT = "agentinbox.direct_text_message";
+const TIMER_INBOX_SOURCE_ID = "__agentinbox_timer__";
+const TIMER_INBOX_EVENT_VARIANT = "agentinbox.timer_fired";
+const DEFAULT_TIMER_SENDER = "timer";
+const MIN_TIMER_INTERVAL_MS = 60 * 1000;
 const WEBHOOK_ACTIVATION_MODES = new Set(["activation_only", "activation_with_items"]);
 const SUBSCRIPTION_START_POLICIES = new Set(["latest", "earliest", "at_offset", "at_time"]);
 class AgentInboxService {
@@ -30,11 +37,12 @@ class AgentInboxService {
     notificationBuffers = new Map();
     inboxWatchers = new Map();
     syncInterval = null;
+    timerSyncTimeout = null;
     stopping = false;
     lastAckedInboxGcAt = 0;
     lastLifecycleCleanupAt = 0;
     lastOfflineAgentGcAt = 0;
-    constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher()) {
+    constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher(), activationGate = new runtime_gate_1.DefaultActivationGate()) {
         this.store = store;
         this.adapters = adapters;
         this.activationDispatcher = activationDispatcher;
@@ -43,9 +51,11 @@ class AgentInboxService {
         this.activationMaxItems = activationPolicy?.maxItems ?? DEFAULT_ACTIVATION_MAX_ITEMS;
         this.ackedRetentionMs = DEFAULT_ACKED_RETENTION_MS;
         this.terminalDispatcher = terminalDispatcher;
+        this.activationGate = activationGate;
     }
     activationDispatcher;
     terminalDispatcher;
+    activationGate;
     async start() {
         if (this.syncInterval) {
             return;
@@ -57,10 +67,12 @@ class AgentInboxService {
             void this.runAckedInboxGcIfDue();
             void this.syncLifecycleGc();
         }, DEFAULT_SYNC_INTERVAL_MS);
+        this.refreshTimersOnStart();
         await this.syncAllSubscriptions();
         await this.syncActivationDispatchStates();
         await this.runAckedInboxGcIfDue(true);
         await this.syncLifecycleGc();
+        await this.syncTimers();
     }
     async stop() {
         this.stopping = true;
@@ -74,7 +86,12 @@ class AgentInboxService {
             clearInterval(this.syncInterval);
             this.syncInterval = null;
         }
+        if (this.timerSyncTimeout) {
+            clearTimeout(this.timerSyncTimeout);
+            this.timerSyncTimeout = null;
+        }
         await this.flushAllPendingNotifications();
+        await this.awaitInFlightNotificationBuffers();
     }
     async registerSource(input) {
         const existing = this.store.getSourceByKey(input.sourceType, input.sourceKey);
@@ -319,6 +336,7 @@ class AgentInboxService {
         return this.registerAgent({
             runtimeKind: detected.runtimeKind,
             runtimeSessionId: detected.runtimeSessionId ?? null,
+            runtimePid: detected.runtimePid ?? null,
             backend: detected.backend,
             mode: "agent_prompt",
             tmuxPaneId: detected.tmuxPaneId ?? null,
@@ -365,8 +383,106 @@ class AgentInboxService {
             }
         });
         this.inboxWatchers.delete(agentId);
+        this.rescheduleTimerSync();
         return { removed: true };
     }
+    registerTimer(input) {
+        this.getAgent(input.agentId);
+        const normalized = normalizeTimerInput(input);
+        const timezone = normalized.timezone ?? detectHostTimezone();
+        assertValidTimeZone(timezone);
+        const now = (0, util_1.nowIso)();
+        const nextFireAt = computeNextTimerFire({
+            mode: normalized.mode,
+            at: normalized.at ?? null,
+            intervalMs: normalized.every ?? null,
+            cronExpr: normalized.cron ?? null,
+            timezone,
+            fromIso: now,
+            lastFiredAt: null,
+            restartRecovery: false,
+        });
+        const timer = {
+            scheduleId: (0, util_1.generateId)("sched"),
+            agentId: input.agentId,
+            status: nextFireAt ? "active" : "paused",
+            mode: normalized.mode,
+            at: normalized.at ?? null,
+            intervalMs: normalized.every ?? null,
+            cronExpr: normalized.cron ?? null,
+            timezone,
+            message: normalizeDirectInboxMessage(input.message),
+            sender: normalizeDirectInboxSender(input.sender) ?? DEFAULT_TIMER_SENDER,
+            nextFireAt,
+            lastFiredAt: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.insertTimer(timer);
+        this.rescheduleTimerSync();
+        return timer;
+    }
+    listTimers(agentId) {
+        if (agentId) {
+            this.getAgent(agentId);
+            return this.store.listTimersForAgent(agentId);
+        }
+        return this.store.listTimers();
+    }
+    getTimer(scheduleId) {
+        const timer = this.store.getTimer(scheduleId);
+        if (!timer) {
+            throw new Error(`unknown timer: ${scheduleId}`);
+        }
+        return timer;
+    }
+    pauseTimer(scheduleId) {
+        const timer = this.getTimer(scheduleId);
+        const updated = this.store.updateTimer(scheduleId, {
+            status: "paused",
+            nextFireAt: null,
+            updatedAt: (0, util_1.nowIso)(),
+        });
+        this.rescheduleTimerSync();
+        return {
+            updated: timer.status !== "paused",
+            timer: updated,
+        };
+    }
+    resumeTimer(scheduleId) {
+        const timer = this.getTimer(scheduleId);
+        if (timer.mode === "at" && timer.lastFiredAt) {
+            throw new Error(`timer ${scheduleId} already fired`);
+        }
+        const now = (0, util_1.nowIso)();
+        const nextFireAt = computeNextTimerFire({
+            mode: timer.mode,
+            at: timer.at ?? null,
+            intervalMs: timer.intervalMs ?? null,
+            cronExpr: timer.cronExpr ?? null,
+            timezone: timer.timezone,
+            fromIso: now,
+            lastFiredAt: timer.lastFiredAt ?? null,
+            restartRecovery: false,
+        });
+        const status = nextFireAt ? "active" : "paused";
+        const updated = this.store.updateTimer(scheduleId, {
+            status,
+            nextFireAt,
+            updatedAt: now,
+        });
+        this.rescheduleTimerSync();
+        return {
+            updated: timer.status !== status,
+            timer: updated,
+        };
+    }
+    removeTimer(scheduleId) {
+        this.getTimer(scheduleId);
+        this.store.deleteTimer(scheduleId);
+        this.rescheduleTimerSync();
+        return { removed: true, scheduleId };
+    }
     addWebhookActivationTarget(agentId, input) {
         this.getAgent(agentId);
         validateNotifyLeaseMs(input.notifyLeaseMs);
@@ -415,6 +531,57 @@ class AgentInboxService {
         this.reconcileAgentStatus(agentId);
         return { removed: true };
     }
+    async resumeAgent(agentId) {
+        this.getAgent(agentId);
+        const targets = this.store.listActivationTargetsForAgent(agentId);
+        const results = [];
+        for (const target of targets) {
+            results.push(await this.resumeActivationTarget(agentId, target.targetId));
+        }
+        this.reconcileAgentStatus(agentId);
+        return {
+            resumed: results.some((result) => result.resumed),
+            agent: this.getAgent(agentId),
+            targets: results,
+        };
+    }
+    async resumeActivationTarget(agentId, targetId) {
+        const target = this.getActivationTarget(targetId);
+        if (target.agentId !== agentId) {
+            throw new Error(`activation target ${targetId} does not belong to agent ${agentId}`);
+        }
+        if (target.status === "active") {
+            return {
+                targetId: target.targetId,
+                resumed: false,
+                status: target.status,
+                reason: "already_active",
+            };
+        }
+        let result;
+        if (target.kind === "terminal") {
+            result = await this.resumeTerminalActivationTarget(target);
+        }
+        else {
+            const now = (0, util_1.nowIso)();
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "active",
+                offlineSince: null,
+                consecutiveFailures: 0,
+                lastError: null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            result = {
+                targetId: target.targetId,
+                resumed: true,
+                status: "active",
+                reason: "webhook_resumed",
+            };
+        }
+        this.reconcileAgentStatus(agentId);
+        return result;
+    }
     async registerSubscription(input) {
         if (input.shortcut) {
             const source = this.store.getSource(input.sourceId);
@@ -578,6 +745,109 @@ class AgentInboxService {
     listInboxItems(agentId, options) {
         return this.store.listInboxItems(this.ensureInboxForAgent(agentId).inboxId, options);
     }
+    async addDirectInboxTextMessage(agentId, input, env = process.env) {
+        this.getAgent(agentId);
+        const message = normalizeDirectInboxMessage(input.message);
+        const sender = normalizeDirectInboxSender(input.sender) ?? this.detectDirectInboxSender(env);
+        return this.materializeAgentInboxItem(agentId, {
+            sourceId: DIRECT_INBOX_SOURCE_ID,
+            sourceNativeId: (0, util_1.generateId)("direct"),
+            eventVariant: DIRECT_INBOX_EVENT_VARIANT,
+            summary: summarizeDirectInboxMessage(sender),
+            rawPayload: {
+                type: "direct_text_message",
+                message,
+                sender,
+            },
+        });
+    }
+    async fireTimer(timer, now) {
+        const scheduledFireAt = timer.nextFireAt ?? now;
+        this.materializeAgentInboxItem(timer.agentId, {
+            sourceId: TIMER_INBOX_SOURCE_ID,
+            sourceNativeId: `${timer.scheduleId}:${scheduledFireAt}`,
+            eventVariant: TIMER_INBOX_EVENT_VARIANT,
+            summary: summarizeTimerMessage(timer.scheduleId),
+            rawPayload: {
+                type: "timer_fired",
+                scheduleId: timer.scheduleId,
+                message: timer.message,
+                sender: timer.sender ?? DEFAULT_TIMER_SENDER,
+            },
+            occurredAt: scheduledFireAt,
+            allowDuplicate: true,
+        });
+        const nextFireAt = computeNextTimerFire({
+            mode: timer.mode,
+            at: timer.at ?? null,
+            intervalMs: timer.intervalMs ?? null,
+            cronExpr: timer.cronExpr ?? null,
+            timezone: timer.timezone,
+            fromIso: scheduledFireAt,
+            lastFiredAt: scheduledFireAt,
+            restartRecovery: false,
+        });
+        this.store.updateTimer(timer.scheduleId, {
+            status: nextFireAt ? "active" : "paused",
+            nextFireAt,
+            lastFiredAt: now,
+            updatedAt: now,
+        });
+    }
+    materializeAgentInboxItem(agentId, input) {
+        const inbox = this.ensureInboxForAgent(agentId);
+        const occurredAt = input.occurredAt ?? (0, util_1.nowIso)();
+        const item = {
+            itemId: (0, util_1.generateId)("item"),
+            sourceId: input.sourceId,
+            sourceNativeId: input.sourceNativeId,
+            eventVariant: input.eventVariant,
+            inboxId: inbox.inboxId,
+            occurredAt,
+            metadata: {},
+            rawPayload: input.rawPayload,
+            deliveryHandle: null,
+            ackedAt: null,
+        };
+        const inserted = this.store.insertInboxItem(item);
+        if (!inserted && !input.allowDuplicate) {
+            throw new Error(`failed to persist direct inbox message item: ${item.itemId}`);
+        }
+        if (!inserted) {
+            return {
+                itemId: item.itemId,
+                inboxId: inbox.inboxId,
+                activated: false,
+            };
+        }
+        this.notifyInboxWatchers(agentId, [item]);
+        const activationItem = {
+            itemId: item.itemId,
+            sourceId: item.sourceId,
+            sourceNativeId: item.sourceNativeId,
+            eventVariant: item.eventVariant,
+            inboxId: item.inboxId,
+            occurredAt: item.occurredAt,
+            metadata: item.metadata,
+            rawPayload: item.rawPayload,
+            deliveryHandle: item.deliveryHandle,
+        };
+        const targets = this.store.listActivationTargetsForAgent(agentId).filter((target) => target.status === "active");
+        for (const target of targets) {
+            this.enqueueActivationTarget(target, {
+                agentId,
+                subscriptionId: null,
+                sourceId: input.sourceId,
+                summary: input.summary,
+                item: activationItem,
+            });
+        }
+        return {
+            itemId: item.itemId,
+            inboxId: inbox.inboxId,
+            activated: targets.length > 0,
+        };
+    }
     watchInbox(agentId, options, onEvent) {
         const inbox = this.ensureInboxForAgent(agentId);
         const pendingItems = [];
@@ -1004,6 +1274,7 @@ class AgentInboxService {
             const target = this.store.updateTerminalActivationTargetHeartbeat(existing.targetId, {
                 runtimeKind: input.runtimeKind ?? "unknown",
                 runtimeSessionId: input.runtimeSessionId ?? null,
+                runtimePid: input.runtimePid ?? null,
                 tmuxPaneId: input.tmuxPaneId ?? null,
                 tty: input.tty ?? null,
                 termProgram: input.termProgram ?? null,
@@ -1030,6 +1301,7 @@ class AgentInboxService {
             notifyLeaseMs: input.notifyLeaseMs ?? DEFAULT_NOTIFY_LEASE_MS,
             runtimeKind: input.runtimeKind ?? "unknown",
             runtimeSessionId: input.runtimeSessionId ?? null,
+            runtimePid: input.runtimePid ?? null,
             backend: input.backend,
             tmuxPaneId: input.tmuxPaneId ?? null,
             tty: input.tty ?? null,
@@ -1111,6 +1383,15 @@ class AgentInboxService {
             await this.flushNotificationBuffer(key);
         }
     }
+    async awaitInFlightNotificationBuffers() {
+        while (true) {
+            const activeBuffers = Array.from(this.notificationBuffers.values());
+            if (activeBuffers.every((buffer) => !buffer.inFlight)) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
     async flushNotificationBuffer(key) {
         const buffer = this.notificationBuffers.get(key);
         if (!buffer || buffer.inFlight || buffer.pending.length === 0) {
@@ -1125,12 +1406,14 @@ class AgentInboxService {
         try {
             const state = this.store.getActivationDispatchState(buffer.agentId, buffer.targetId);
             if (!state) {
+                const inbox = this.ensureInboxForAgent(buffer.agentId);
                 const dispatched = await this.dispatchActivationTarget({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
                     newItemCount: entries.length,
+                    totalUnackedCount: this.store.countInboxItems(inbox.inboxId, false),
                     summary: entries[0]?.summary ?? null,
-                    subscriptionIds: uniqueSorted(entries.map((entry) => entry.subscriptionId)),
+                    subscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
                     sourceIds: uniqueSorted(entries.map((entry) => entry.sourceId)),
                     items: entries.map((entry) => entry.item),
                 });
@@ -1146,7 +1429,7 @@ class AgentInboxService {
                     leaseExpiresAt: state.leaseExpiresAt,
                     pendingNewItemCount: state.pendingNewItemCount + entries.length,
                     pendingSummary: state.pendingSummary ?? entries[0]?.summary ?? null,
-                    pendingSubscriptionIds: uniqueSorted([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
+                    pendingSubscriptionIds: uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
                     pendingSourceIds: uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]),
                     updatedAt: (0, util_1.nowIso)(),
                 });
@@ -1154,9 +1437,11 @@ class AgentInboxService {
             const hasPendingDuringFlight = buffer.pending.length > 0;
             buffer.inFlight = false;
             if (hasPendingDuringFlight) {
-                buffer.timer = setTimeout(() => {
-                    void this.flushNotificationBuffer(key);
-                }, this.activationWindowMs);
+                if (!this.stopping) {
+                    buffer.timer = setTimeout(() => {
+                        void this.flushNotificationBuffer(key);
+                    }, this.activationWindowMs);
+                }
                 return;
             }
             this.notificationBuffers.delete(key);
@@ -1196,6 +1481,7 @@ class AgentInboxService {
             agentId,
             targetId,
             newItemCount: state.pendingNewItemCount > 0 ? state.pendingNewItemCount : unacked,
+            totalUnackedCount: unacked,
             summary: state.pendingSummary,
             subscriptionIds: state.pendingSubscriptionIds,
             sourceIds: state.pendingSourceIds,
@@ -1231,11 +1517,32 @@ class AgentInboxService {
         }
         const inbox = this.ensureInboxForAgent(input.agentId);
         const summary = summarizeActivation(inbox.inboxId, input.newItemCount, input.summary);
+        const totalUnackedCount = input.totalUnackedCount ?? this.store.countInboxItems(inbox.inboxId, false);
         try {
             if (target.kind === "terminal") {
+                const gate = await this.activationGate.evaluate(target);
+                if (gate.outcome === "offline") {
+                    this.markActivationTargetOffline(target.targetId, `runtime gate: ${gate.reason}`);
+                    this.reconcileAgentStatus(target.agentId);
+                    return "offline";
+                }
+                if (gate.outcome === "defer") {
+                    this.store.upsertActivationDispatchState({
+                        agentId: input.agentId,
+                        targetId: input.targetId,
+                        status: "dirty",
+                        leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+                        pendingNewItemCount: input.newItemCount,
+                        pendingSummary: input.summary,
+                        pendingSubscriptionIds: uniqueSortedNullable(input.subscriptionIds),
+                        pendingSourceIds: uniqueSorted(input.sourceIds),
+                        updatedAt: (0, util_1.nowIso)(),
+                    });
+                    return "deferred";
+                }
                 const prompt = (0, terminal_1.renderAgentPrompt)({
                     inboxId: inbox.inboxId,
-                    newItemCount: input.newItemCount,
+                    totalUnackedCount,
                     summary: input.summary,
                 });
                 await this.terminalDispatcher.dispatch(target, prompt);
@@ -1297,11 +1604,37 @@ class AgentInboxService {
             leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
             pendingNewItemCount: entries.length,
             pendingSummary: entries[0]?.summary ?? null,
-            pendingSubscriptionIds: uniqueSorted(entries.map((entry) => entry.subscriptionId)),
+            pendingSubscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
             pendingSourceIds: uniqueSorted(entries.map((entry) => entry.sourceId)),
             updatedAt: (0, util_1.nowIso)(),
         });
     }
+    detectDirectInboxSender(env) {
+        try {
+            const detected = (0, terminal_1.detectTerminalContext)(env);
+            const target = findExistingTerminalActivationTarget(this.store, {
+                runtimeKind: detected.runtimeKind,
+                runtimeSessionId: detected.runtimeSessionId ?? null,
+                runtimePid: detected.runtimePid ?? null,
+                backend: detected.backend,
+                tmuxPaneId: detected.tmuxPaneId ?? null,
+                tty: detected.tty ?? null,
+                termProgram: detected.termProgram ?? null,
+                itermSessionId: detected.itermSessionId ?? null,
+            });
+            if (target) {
+                return target.agentId;
+            }
+            return detected.runtimeSessionId
+                ?? detected.tmuxPaneId
+                ?? detected.itermSessionId
+                ?? detected.tty
+                ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
     markActivationTargetDelivered(targetId) {
         const now = (0, util_1.nowIso)();
         this.store.updateActivationTargetRuntime(targetId, {
@@ -1366,6 +1699,46 @@ class AgentInboxService {
             lastSeenAt: agent.lastSeenAt,
         });
     }
+    async resumeTerminalActivationTarget(target) {
+        const probeStatus = await this.terminalDispatcher.probeStatus(target);
+        const now = (0, util_1.nowIso)();
+        if (probeStatus === "available") {
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "active",
+                offlineSince: null,
+                consecutiveFailures: 0,
+                lastError: null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            return {
+                targetId: target.targetId,
+                resumed: true,
+                status: "active",
+                reason: "terminal_available",
+            };
+        }
+        if (probeStatus === "gone") {
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "offline",
+                offlineSince: target.offlineSince ?? now,
+                updatedAt: now,
+                lastError: target.lastError ?? "terminal gone",
+            });
+            return {
+                targetId: target.targetId,
+                resumed: false,
+                status: "offline",
+                reason: "terminal_gone",
+            };
+        }
+        return {
+            targetId: target.targetId,
+            resumed: false,
+            status: "offline",
+            reason: "probe_unknown",
+        };
+    }
     runLifecycleCleanupPass(nowMs) {
         this.lastLifecycleCleanupAt = nowMs;
         const removed = new Set();
@@ -1474,6 +1847,9 @@ class AgentInboxService {
         if (agents.length > 0) {
             this.store.save();
         }
+        if (agents.length > 0) {
+            this.rescheduleTimerSync();
+        }
         return { removedAgents: agents.length };
     }
     async syncAllSubscriptions() {
@@ -1531,6 +1907,64 @@ class AgentInboxService {
             console.warn("offline agent gc failed:", error);
         }
     }
+    async syncTimers() {
+        const now = (0, util_1.nowIso)();
+        const due = this.store.listDueTimers(now);
+        for (const timer of due) {
+            try {
+                await this.fireTimer(timer, now);
+            }
+            catch (error) {
+                console.warn(`timer fire failed for ${timer.scheduleId}:`, error);
+            }
+        }
+        this.rescheduleTimerSync();
+    }
+    refreshTimersOnStart() {
+        const now = (0, util_1.nowIso)();
+        for (const timer of this.store.listTimers()) {
+            if (timer.status !== "active") {
+                continue;
+            }
+            const nextFireAt = computeNextTimerFire({
+                mode: timer.mode,
+                at: timer.at ?? null,
+                intervalMs: timer.intervalMs ?? null,
+                cronExpr: timer.cronExpr ?? null,
+                timezone: timer.timezone,
+                fromIso: now,
+                lastFiredAt: timer.lastFiredAt ?? null,
+                restartRecovery: true,
+            });
+            this.store.updateTimer(timer.scheduleId, {
+                nextFireAt,
+                status: nextFireAt ? "active" : "paused",
+                updatedAt: now,
+            });
+        }
+    }
+    rescheduleTimerSync() {
+        if (this.timerSyncTimeout) {
+            clearTimeout(this.timerSyncTimeout);
+            this.timerSyncTimeout = null;
+        }
+        if (this.stopping) {
+            return;
+        }
+        const nearest = this.store.getNearestActiveTimer();
+        if (!nearest?.nextFireAt) {
+            return;
+        }
+        const dueAt = Date.parse(nearest.nextFireAt);
+        if (Number.isNaN(dueAt)) {
+            return;
+        }
+        const delay = Math.max(0, dueAt - Date.now());
+        this.timerSyncTimeout = setTimeout(() => {
+            this.timerSyncTimeout = null;
+            void this.syncTimers();
+        }, delay);
+    }
     refreshSourceIdleState(sourceId) {
         const source = this.store.getSource(sourceId);
         if (!source) {
@@ -1841,6 +2275,9 @@ function isSameTerminalIdentity(target, input) {
 function uniqueSorted(values) {
     return Array.from(new Set(values)).sort();
 }
+function uniqueSortedNullable(values) {
+    return uniqueSorted(values.filter((value) => typeof value === "string" && value.length > 0));
+}
 function notificationBufferKey(agentId, targetId) {
     return `${agentId}::${targetId}`;
 }
@@ -1873,3 +2310,299 @@ function summarizeSourceEvent(sourceType, sourceKey, eventVariant) {
     }
     return `${sourceType}:${sourceKey}:${eventVariant}`;
 }
+function summarizeDirectInboxMessage(sender) {
+    if (sender) {
+        return `direct_text_message:${sender}`;
+    }
+    return "direct_text_message";
+}
+function summarizeTimerMessage(scheduleId) {
+    return `timer:${scheduleId}`;
+}
+function normalizeDirectInboxMessage(message) {
+    if (typeof message !== "string") {
+        throw new Error("direct inbox message must be a string");
+    }
+    const trimmed = message.trim();
+    if (trimmed.length === 0) {
+        throw new Error("direct inbox message must not be empty");
+    }
+    return trimmed;
+}
+function normalizeDirectInboxSender(sender) {
+    if (sender == null) {
+        return null;
+    }
+    if (typeof sender !== "string") {
+        throw new Error("direct inbox sender must be a string");
+    }
+    const trimmed = sender.trim();
+    if (trimmed.length === 0) {
+        throw new Error("direct inbox sender must not be empty");
+    }
+    return trimmed;
+}
+function normalizeTimerInput(input) {
+    const modes = [input.at != null, input.every != null, input.cron != null].filter(Boolean).length;
+    if (modes !== 1) {
+        throw new Error("timers require exactly one of at, every, or cron");
+    }
+    if (input.at != null) {
+        const at = normalizeIsoTimestamp(input.at, "timer at");
+        return { mode: "at", at, timezone: input.timezone ?? null };
+    }
+    if (input.every != null) {
+        if (!Number.isInteger(input.every) || input.every < MIN_TIMER_INTERVAL_MS) {
+            throw new Error("timer every interval must be an integer number of milliseconds and at least 60000");
+        }
+        return { mode: "every", every: input.every, timezone: input.timezone ?? null };
+    }
+    const cron = normalizeCronExpression(input.cron);
+    return { mode: "cron", cron, timezone: input.timezone ?? null };
+}
+function normalizeIsoTimestamp(value, label) {
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`${label} must be a valid ISO8601 timestamp`);
+    }
+    return new Date(parsed).toISOString();
+}
+function normalizeCronExpression(value) {
+    if (typeof value !== "string") {
+        throw new Error("timer cron must be a string");
+    }
+    const trimmed = value.trim().replace(/\s+/g, " ");
+    const fields = trimmed.split(" ");
+    if (fields.length !== 5) {
+        throw new Error("timer cron must use standard 5-field syntax");
+    }
+    for (const field of fields) {
+        if (/[LW#@]/.test(field)) {
+            throw new Error("timer cron does not support extensions like L, W, #, or @reboot");
+        }
+    }
+    parseCronExpression(trimmed);
+    return trimmed;
+}
+function detectHostTimezone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+function assertValidTimeZone(timezone) {
+    try {
+        Intl.DateTimeFormat("en-US", { timeZone: timezone }).format(new Date());
+    }
+    catch {
+        throw new Error(`invalid timezone: ${timezone}`);
+    }
+}
+function computeNextTimerFire(input) {
+    const fromMs = Date.parse(input.fromIso);
+    if (Number.isNaN(fromMs)) {
+        return null;
+    }
+    if (input.mode === "at") {
+        if (!input.at) {
+            return null;
+        }
+        const atMs = Date.parse(input.at);
+        if (Number.isNaN(atMs)) {
+            return null;
+        }
+        if (input.lastFiredAt) {
+            return null;
+        }
+        if (atMs <= fromMs) {
+            return input.restartRecovery ? input.at : input.at;
+        }
+        return input.at;
+    }
+    if (input.mode === "every") {
+        if (!input.intervalMs) {
+            return null;
+        }
+        if (!input.lastFiredAt) {
+            return new Date(fromMs + input.intervalMs).toISOString();
+        }
+        const lastFiredMs = Date.parse(input.lastFiredAt);
+        if (Number.isNaN(lastFiredMs)) {
+            return new Date(fromMs + input.intervalMs).toISOString();
+        }
+        const base = input.restartRecovery ? fromMs : Math.max(fromMs, lastFiredMs);
+        return new Date(base + input.intervalMs).toISOString();
+    }
+    if (!input.cronExpr) {
+        return null;
+    }
+    return nextCronOccurrence(input.cronExpr, input.timezone, new Date(fromMs));
+}
+function parseCronExpression(expr) {
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = expr.split(" ");
+    return {
+        minute: parseCronField(minute, 0, 59),
+        hour: parseCronField(hour, 0, 23),
+        dayOfMonth: parseCronField(dayOfMonth, 1, 31),
+        month: parseCronField(month, 1, 12),
+        dayOfWeek: parseCronField(dayOfWeek, 0, 7, true),
+    };
+}
+function parseCronField(field, min, max, normalizeSunday = false) {
+    if (field === "*") {
+        return { any: true, values: new Set() };
+    }
+    const values = new Set();
+    for (const part of field.split(",")) {
+        const [rangePart, stepPart] = part.split("/");
+        const step = stepPart ? Number(stepPart) : 1;
+        if (!Number.isInteger(step) || step <= 0) {
+            throw new Error(`invalid cron field: ${field}`);
+        }
+        const [startRaw, endRaw] = rangePart === "*" ? [String(min), String(max)] : rangePart.split("-");
+        const start = Number(startRaw);
+        const end = endRaw != null ? Number(endRaw) : start;
+        if (!Number.isInteger(start) || !Number.isInteger(end) || start < min || end > max || start > end) {
+            throw new Error(`invalid cron field: ${field}`);
+        }
+        for (let value = start; value <= end; value += step) {
+            values.add(normalizeSunday && value === 7 ? 0 : value);
+        }
+    }
+    return { any: false, values };
+}
+function nextCronOccurrence(expr, timezone, after) {
+    const parsed = parseCronExpression(expr);
+    let candidate = addMinutes(after, 1);
+    candidate.setUTCSeconds(0, 0);
+    for (let guard = 0; guard < 10_000; guard += 1) {
+        const zoned = zonedDateParts(candidate, timezone);
+        const nextMonth = nextAllowedValue(parsed.month, zoned.month, 1, 12);
+        if (nextMonth == null) {
+            candidate = utcDateForZoned(timezone, zoned.year + 1, firstAllowedValue(parsed.month, 1, 12), 1, 0, 0);
+            continue;
+        }
+        if (nextMonth !== zoned.month) {
+            candidate = utcDateForZoned(timezone, zoned.year, nextMonth, 1, 0, 0);
+            continue;
+        }
+        if (!matchesCronDay(parsed, zoned)) {
+            candidate = utcDateForZoned(timezone, zoned.year, zoned.month, zoned.day + 1, 0, 0);
+            continue;
+        }
+        const nextHour = nextAllowedValue(parsed.hour, zoned.hour, 0, 23);
+        if (nextHour == null) {
+            candidate = utcDateForZoned(timezone, zoned.year, zoned.month, zoned.day + 1, firstAllowedValue(parsed.hour, 0, 23), 0);
+            continue;
+        }
+        if (nextHour !== zoned.hour) {
+            candidate = utcDateForZoned(timezone, zoned.year, zoned.month, zoned.day, nextHour, 0);
+            continue;
+        }
+        const nextMinute = nextAllowedValue(parsed.minute, zoned.minute, 0, 59);
+        if (nextMinute == null) {
+            candidate = utcDateForZoned(timezone, zoned.year, zoned.month, zoned.day, zoned.hour + 1, firstAllowedValue(parsed.minute, 0, 59));
+            continue;
+        }
+        if (nextMinute !== zoned.minute) {
+            candidate = utcDateForZoned(timezone, zoned.year, zoned.month, zoned.day, zoned.hour, nextMinute);
+            continue;
+        }
+        if (matchesCron(parsed, zoned)) {
+            return candidate.toISOString();
+        }
+        candidate = addMinutes(candidate, 1);
+    }
+    return null;
+}
+function matchesCron(parsed, parts) {
+    const monthMatches = parsed.month.any || parsed.month.values.has(parts.month);
+    const hourMatches = parsed.hour.any || parsed.hour.values.has(parts.hour);
+    const minuteMatches = parsed.minute.any || parsed.minute.values.has(parts.minute);
+    if (!monthMatches || !hourMatches || !minuteMatches) {
+        return false;
+    }
+    const dayOfMonthMatches = parsed.dayOfMonth.any || parsed.dayOfMonth.values.has(parts.day);
+    const dayOfWeekMatches = parsed.dayOfWeek.any || parsed.dayOfWeek.values.has(parts.dayOfWeek);
+    if (!parsed.dayOfMonth.any && !parsed.dayOfWeek.any) {
+        return dayOfMonthMatches || dayOfWeekMatches;
+    }
+    return dayOfMonthMatches && dayOfWeekMatches;
+}
+function matchesCronDay(parsed, parts) {
+    const dayOfMonthMatches = parsed.dayOfMonth.any || parsed.dayOfMonth.values.has(parts.day);
+    const dayOfWeekMatches = parsed.dayOfWeek.any || parsed.dayOfWeek.values.has(parts.dayOfWeek);
+    if (!parsed.dayOfMonth.any && !parsed.dayOfWeek.any) {
+        return dayOfMonthMatches || dayOfWeekMatches;
+    }
+    return dayOfMonthMatches && dayOfWeekMatches;
+}
+function zonedDateParts(date, timezone) {
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+        weekday: "short",
+    });
+    const entries = Object.fromEntries(formatter.formatToParts(date)
+        .filter((part) => part.type !== "literal")
+        .map((part) => [part.type, part.value]));
+    const hour = Number(entries.hour);
+    return {
+        year: Number(entries.year),
+        month: Number(entries.month),
+        day: Number(entries.day),
+        // Some ICU builds format midnight as 24:00 even for exact timestamps.
+        // Normalize that representation so cron matching stays cross-platform.
+        hour: hour === 24 ? 0 : hour,
+        minute: Number(entries.minute),
+        dayOfWeek: weekdayToNumber(entries.weekday),
+    };
+}
+function nextAllowedValue(field, current, min, max) {
+    if (field.any) {
+        return current;
+    }
+    for (let value = current; value <= max; value += 1) {
+        if (field.values.has(value)) {
+            return value;
+        }
+    }
+    return null;
+}
+function firstAllowedValue(field, min, max) {
+    if (field.any) {
+        return min;
+    }
+    for (let value = min; value <= max; value += 1) {
+        if (field.values.has(value)) {
+            return value;
+        }
+    }
+    return min;
+}
+function addMinutes(date, minutes) {
+    return new Date(date.getTime() + minutes * 60_000);
+}
+function utcDateForZoned(timezone, year, month, day, hour, minute) {
+    const approxUtc = Date.UTC(year, month - 1, day, hour, minute, 0, 0);
+    const approx = new Date(approxUtc);
+    const zoned = zonedDateParts(approx, timezone);
+    const targetNaiveUtc = Date.UTC(year, month - 1, day, hour, minute, 0, 0);
+    const zonedNaiveUtc = Date.UTC(zoned.year, zoned.month - 1, zoned.day, zoned.hour, zoned.minute, 0, 0);
+    return new Date(approxUtc - (zonedNaiveUtc - targetNaiveUtc));
+}
+function weekdayToNumber(value) {
+    switch (value) {
+        case "Sun": return 0;
+        case "Mon": return 1;
+        case "Tue": return 2;
+        case "Wed": return 3;
+        case "Thu": return 4;
+        case "Fri": return 5;
+        case "Sat": return 6;
+        default:
+            throw new Error(`unsupported weekday: ${value}`);
+    }
+}