@holon-run/agentinbox 0.1.4 → 0.3.0

package/dist/src/service.js

@@ -4,8 +4,10 @@ exports.ActivationDispatcher = exports.AgentInboxService = void 0;
 const backend_1 = require("./backend");
 const util_1 = require("./util");
 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;
@@ -14,9 +16,16 @@ const DEFAULT_NOTIFY_RETRY_MS = 5_000;
 const DEFAULT_ACKED_RETENTION_MS = 24 * 60 * 60 * 1000;
 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"]);
-const SUBSCRIPTION_LIFECYCLE_MODES = new Set(["standing", "temporary"]);
 class AgentInboxService {
     store;
     adapters;
@@ -28,10 +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;
@@ -40,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;
@@ -53,11 +66,13 @@ class AgentInboxService {
             void this.syncActivationDispatchStates();
             void this.runAckedInboxGcIfDue();
             void this.syncLifecycleGc();
-        }, 2_000);
+        }, 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;
@@ -71,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);
@@ -105,30 +125,91 @@ class AgentInboxService {
         }
         return source;
     }
-    getSourceDetails(sourceId) {
+    async getSourceDetails(sourceId) {
         const source = this.getSource(sourceId);
+        const fallbackSchema = (0, source_schema_1.getSourceSchema)(source.sourceType);
+        let resolvedIdentity = null;
+        let resolutionError = null;
+        let schema = fallbackSchema;
+        try {
+            resolvedIdentity = await this.adapters.resolveSourceIdentity(source);
+            schema = await this.adapters.resolveSourceSchema(source);
+        }
+        catch (error) {
+            resolutionError = error instanceof Error ? error.message : String(error);
+        }
+        const resolvedSchema = resolvedIdentity
+            ? ("hostType" in schema
+                ? schema
+                : (0, source_resolution_1.withResolvedIdentity)(source.sourceId, fallbackSchema, resolvedIdentity))
+            : fallbackSchema;
         return {
             source,
-            schema: (0, source_schema_1.getSourceSchema)(source.sourceType),
+            resolvedIdentity,
+            ...(resolutionError ? { resolutionError } : {}),
+            schema: resolvedSchema,
             stream: this.store.getStreamBySourceId(sourceId),
             subscriptions: this.store.listSubscriptionsForSource(sourceId),
+            idleState: this.store.getSourceIdleState(sourceId),
         };
     }
     getSourceSchema(sourceType) {
         return (0, source_schema_1.getSourceSchema)(sourceType);
     }
-    async removeSource(sourceId) {
+    async getResolvedSourceSchema(sourceId) {
+        const source = this.getSource(sourceId);
+        return this.adapters.resolveSourceSchema(source);
+    }
+    async previewSourceSchema(input) {
+        try {
+            const source = buildPreviewSource(input);
+            await this.adapters.sourceAdapterFor(source.sourceType).validateSource?.(source);
+            const schema = await this.adapters.resolveSourceSchema(source);
+            if (input.sourceRef.startsWith("remote:")) {
+                const expectedImplementationId = input.sourceRef.slice("remote:".length);
+                if (schema.implementationId !== expectedImplementationId) {
+                    throw new Error(`preview source kind ${input.sourceRef} resolved to implementation ${schema.implementationId}`);
+                }
+            }
+            const { sourceId: _sourceId, ...preview } = schema;
+            return preview;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.startsWith("preview failed: ") || message.startsWith("preview source kind ")) {
+                throw error;
+            }
+            throw new Error(`preview failed: ${message}`);
+        }
+    }
+    async removeSource(sourceId, options = {}) {
         const source = this.store.getSource(sourceId);
         if (!source) {
-            return { removed: false };
+            return { removed: false, sourceId, removedSubscriptions: 0, pausedSource: false };
         }
         const subscriptions = this.store.listSubscriptionsForSource(sourceId);
-        if (subscriptions.length > 0) {
-            throw new Error("source remove requires no active subscriptions");
+        if (subscriptions.length > 0 && !options.withSubscriptions) {
+            throw new Error("source remove requires no active subscriptions; retry with --with-subscriptions or with_subscriptions=true");
+        }
+        let pausedSource = false;
+        if (options.withSubscriptions) {
+            const sourceAdapter = this.adapters.sourceAdapterFor(source.sourceType);
+            if (sourceAdapter.pauseSource) {
+                await this.pauseSource(sourceId);
+                pausedSource = true;
+            }
+            for (const subscription of subscriptions) {
+                await this.removeSubscription(subscription.subscriptionId);
+            }
         }
         await this.adapters.removeSource(source);
         this.store.deleteSource(sourceId);
-        return { removed: true };
+        return {
+            removed: true,
+            sourceId,
+            removedSubscriptions: subscriptions.length,
+            pausedSource,
+        };
     }
     async updateSource(sourceId, input) {
         const source = this.store.getSource(sourceId);
@@ -183,6 +264,7 @@ class AgentInboxService {
         if (this.store.getSource(sourceId)?.status !== "paused") {
             this.store.updateSourceRuntime(sourceId, { status: "paused" });
         }
+        this.store.deleteSourceIdleState(sourceId);
         return {
             paused: true,
             source: this.getSource(sourceId),
@@ -197,6 +279,7 @@ class AgentInboxService {
         if (this.store.getSource(sourceId)?.status === "paused") {
             this.store.updateSourceRuntime(sourceId, { status: "active" });
         }
+        this.store.deleteSourceIdleState(sourceId);
         return {
             resumed: true,
             source: this.getSource(sourceId),
@@ -253,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,
@@ -285,7 +369,11 @@ class AgentInboxService {
     }
     removeAgent(agentId) {
         this.getAgent(agentId);
+        const affectedSourceIds = Array.from(new Set(this.store.listSubscriptionsForAgent(agentId).map((subscription) => subscription.sourceId)));
         this.store.deleteAgent(agentId);
+        for (const sourceId of affectedSourceIds) {
+            this.refreshSourceIdleState(sourceId);
+        }
         this.notificationBuffers.forEach((buffer, key) => {
             if (key.startsWith(`${agentId}:`)) {
                 if (buffer.timer) {
@@ -295,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);
@@ -346,23 +532,47 @@ class AgentInboxService {
         return { removed: true };
     }
     async registerSubscription(input) {
+        if (input.shortcut) {
+            const source = this.store.getSource(input.sourceId);
+            if (!source) {
+                throw new Error(`unknown source: ${input.sourceId}`);
+            }
+            if (hasSubscriptionFieldOverride(input)) {
+                throw new Error("subscription add shortcut does not allow filter, trackedResourceRef, or cleanupPolicy overrides");
+            }
+            const expanded = await this.adapters.expandSubscriptionShortcut(source, input.shortcut);
+            if (!expanded) {
+                throw new Error(`unknown subscription shortcut ${input.shortcut.name} for source ${input.sourceId}`);
+            }
+            return this.registerSubscription({
+                ...input,
+                shortcut: undefined,
+                filter: expanded.filter,
+                trackedResourceRef: expanded.trackedResourceRef ?? null,
+                cleanupPolicy: expanded.cleanupPolicy,
+            });
+        }
         this.getAgent(input.agentId);
         const source = this.store.getSource(input.sourceId);
         if (!source) {
             throw new Error(`unknown source: ${input.sourceId}`);
         }
         await (0, filter_1.validateSubscriptionFilter)(input.filter ?? {});
-        const lifecycleMode = input.lifecycleMode ?? "standing";
-        if (!SUBSCRIPTION_LIFECYCLE_MODES.has(lifecycleMode)) {
-            throw new Error(`unsupported lifecycle mode: ${lifecycleMode}`);
+        const cleanupPolicy = normalizeCleanupPolicy(input.cleanupPolicy ?? null);
+        const idleState = this.store.getSourceIdleState(source.sourceId);
+        if (idleState?.autoPausedAt) {
+            await this.resumeSource(source.sourceId);
+        }
+        else if (idleState) {
+            this.store.deleteSourceIdleState(source.sourceId);
         }
         const subscription = {
             subscriptionId: (0, util_1.generateId)("sub"),
             agentId: input.agentId,
             sourceId: input.sourceId,
             filter: input.filter ?? {},
-            lifecycleMode,
-            expiresAt: input.expiresAt ?? null,
+            trackedResourceRef: normalizeTrackedResourceRef(input.trackedResourceRef),
+            cleanupPolicy,
             startPolicy: input.startPolicy ?? "latest",
             startOffset: input.startOffset ?? null,
             startTime: input.startTime ?? null,
@@ -379,6 +589,7 @@ class AgentInboxService {
             startOffset: subscription.startOffset ?? null,
             startTime: subscription.startTime ?? null,
         });
+        this.store.deleteSourceIdleState(source.sourceId);
         return subscription;
     }
     async removeSubscription(subscriptionId) {
@@ -386,6 +597,7 @@ class AgentInboxService {
         await this.backend.deleteConsumer({ subscriptionId });
         this.store.deleteSubscription(subscriptionId);
         this.clearSubscriptionRuntimeState(subscription);
+        this.refreshSourceIdleState(subscription.sourceId);
         return { removed: true, subscriptionId };
     }
     listSubscriptions(filters) {
@@ -482,6 +694,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 = [];
@@ -598,11 +913,13 @@ class AgentInboxService {
     }
     gc() {
         const acked = this.gcAckedInboxItems();
-        const lifecycle = this.gcOfflineAgents();
+        const lifecycle = this.runLifecycleCleanupPass(Date.now());
+        const offlineAgents = this.gcOfflineAgents();
         return {
             deleted: acked.deleted,
             retentionMs: acked.retentionMs,
-            removedAgents: lifecycle.removedAgents,
+            removedAgents: offlineAgents.removedAgents,
+            removedSubscriptions: lifecycle.removedSubscriptions,
         };
     }
     async pollSource(sourceId) {
@@ -645,9 +962,11 @@ class AgentInboxService {
             let inboxItemsCreated = 0;
             let lastProcessedOffset = null;
             const insertedItems = [];
+            const lifecycleSignals = new Map();
             try {
                 for (const event of batch.events) {
                     lastProcessedOffset = event.offset;
+                    await this.collectLifecycleSignal(source, event.rawPayload, lifecycleSignals, event.occurredAt);
                     const match = await (0, filter_1.matchSubscriptionFilter)(subscription.filter, {
                         metadata: event.metadata,
                         payload: event.rawPayload,
@@ -720,6 +1039,9 @@ class AgentInboxService {
                     committedOffset: lastProcessedOffset,
                 });
             }
+            for (const signal of lifecycleSignals.values()) {
+                this.scheduleLifecycleRetirements(source, subscription, signal);
+            }
             return {
                 subscriptionId: subscription.subscriptionId,
                 sourceId: subscription.sourceId,
@@ -818,6 +1140,52 @@ class AgentInboxService {
             backend: "sqlite",
         });
     }
+    async collectLifecycleSignal(source, rawPayload, signals, fallbackOccurredAt) {
+        const signal = await this.adapters.projectLifecycleSignal(source, rawPayload);
+        if (!signal || !signal.terminal) {
+            return;
+        }
+        const normalized = normalizeLifecycleSignal(signal, fallbackOccurredAt);
+        if (!normalized) {
+            return;
+        }
+        const existing = signals.get(normalized.ref);
+        if (!existing) {
+            signals.set(normalized.ref, normalized);
+            return;
+        }
+        const existingAt = Date.parse(existing.occurredAt ?? "");
+        const normalizedAt = Date.parse(normalized.occurredAt ?? "");
+        if (Number.isNaN(existingAt) || (!Number.isNaN(normalizedAt) && normalizedAt > existingAt)) {
+            signals.set(normalized.ref, normalized);
+        }
+    }
+    scheduleLifecycleRetirements(source, subscription, signal) {
+        if (!signal.terminal) {
+            return;
+        }
+        if (!subscription.trackedResourceRef || subscription.trackedResourceRef !== signal.ref) {
+            return;
+        }
+        const signalOccurredAt = signal.occurredAt ?? (0, util_1.nowIso)();
+        const signalOccurredAtMs = Date.parse(signalOccurredAt);
+        const retireAt = lifecycleRetireAtForSignal(subscription.cleanupPolicy, signalOccurredAtMs);
+        if (!retireAt) {
+            return;
+        }
+        const now = (0, util_1.nowIso)();
+        this.store.upsertSubscriptionLifecycleRetirement({
+            subscriptionId: subscription.subscriptionId,
+            sourceId: source.sourceId,
+            trackedResourceRef: signal.ref,
+            retireAt,
+            terminalState: signal.state ?? null,
+            terminalResult: signal.result ?? null,
+            terminalOccurredAt: signalOccurredAt,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
     notifyInboxWatchers(agentId, items) {
         const watchers = this.inboxWatchers.get(agentId);
         if (!watchers || watchers.size === 0) {
@@ -855,6 +1223,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,
@@ -881,6 +1250,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,
@@ -954,6 +1324,7 @@ class AgentInboxService {
             // state so future subscriptions do not inherit a stale notified window.
             this.store.deleteActivationDispatchState(state.agentId, state.targetId);
         }
+        this.store.deleteSubscriptionLifecycleRetirement(subscription.subscriptionId);
     }
     async flushAllPendingNotifications() {
         const keys = Array.from(this.notificationBuffers.keys());
@@ -961,6 +1332,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) {
@@ -980,7 +1360,7 @@ class AgentInboxService {
                     targetId: buffer.targetId,
                     newItemCount: entries.length,
                     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),
                 });
@@ -996,7 +1376,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)(),
                 });
@@ -1004,9 +1384,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);
@@ -1083,6 +1465,26 @@ class AgentInboxService {
         const summary = summarizeActivation(inbox.inboxId, input.newItemCount, input.summary);
         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,
@@ -1147,11 +1549,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, {
@@ -1216,10 +1644,97 @@ class AgentInboxService {
             lastSeenAt: agent.lastSeenAt,
         });
     }
+    runLifecycleCleanupPass(nowMs) {
+        this.lastLifecycleCleanupAt = nowMs;
+        const removed = new Set();
+        const affectedSourceIds = new Set();
+        for (const subscription of this.store.listSubscriptions()) {
+            if (removed.has(subscription.subscriptionId)) {
+                continue;
+            }
+            const deadline = lifecycleDeadlineAt(subscription.cleanupPolicy);
+            if (!deadline) {
+                continue;
+            }
+            const deadlineMs = Date.parse(deadline);
+            if (Number.isNaN(deadlineMs) || deadlineMs > nowMs) {
+                continue;
+            }
+            if (this.store.deleteSubscription(subscription.subscriptionId)) {
+                removed.add(subscription.subscriptionId);
+                affectedSourceIds.add(subscription.sourceId);
+                this.clearSubscriptionRuntimeState(subscription);
+            }
+        }
+        const dueRetirements = this.store.listSubscriptionLifecycleRetirementsDue(new Date(nowMs).toISOString());
+        for (const retirement of dueRetirements) {
+            if (removed.has(retirement.subscriptionId)) {
+                this.store.deleteSubscriptionLifecycleRetirement(retirement.subscriptionId);
+                continue;
+            }
+            const subscription = this.store.getSubscription(retirement.subscriptionId);
+            if (!subscription) {
+                this.store.deleteSubscriptionLifecycleRetirement(retirement.subscriptionId);
+                continue;
+            }
+            if (this.store.deleteSubscription(retirement.subscriptionId)) {
+                removed.add(retirement.subscriptionId);
+                affectedSourceIds.add(subscription.sourceId);
+                this.clearSubscriptionRuntimeState(subscription);
+            }
+        }
+        return {
+            removedSubscriptions: removed.size,
+            affectedSourceIds: [...affectedSourceIds],
+        };
+    }
+    async runIdleSourceCleanupPass(nowMs) {
+        const now = new Date(nowMs).toISOString();
+        const due = this.store.listSourceIdleStatesDue(now);
+        for (const idleState of due) {
+            const source = this.store.getSource(idleState.sourceId);
+            if (!source) {
+                this.store.deleteSourceIdleState(idleState.sourceId);
+                continue;
+            }
+            if (this.store.listSubscriptionsForSource(source.sourceId).length > 0) {
+                this.store.deleteSourceIdleState(source.sourceId);
+                continue;
+            }
+            const sourceAdapter = this.adapters.sourceAdapterFor(source.sourceType);
+            if (!sourceAdapter.pauseSource) {
+                this.store.deleteSourceIdleState(source.sourceId);
+                continue;
+            }
+            if (source.status === "paused") {
+                if (!idleState.autoPausedAt) {
+                    this.store.upsertSourceIdleState({
+                        ...idleState,
+                        autoPausedAt: now,
+                        updatedAt: now,
+                    });
+                }
+                continue;
+            }
+            await this.adapters.pauseSource(source);
+            if (this.store.getSource(source.sourceId)?.status !== "paused") {
+                this.store.updateSourceRuntime(source.sourceId, { status: "paused" });
+            }
+            this.store.upsertSourceIdleState({
+                ...idleState,
+                autoPausedAt: now,
+                updatedAt: now,
+            });
+        }
+    }
     gcOfflineAgents(now = Date.now()) {
         const cutoffIso = new Date(now - DEFAULT_OFFLINE_AGENT_TTL_MS).toISOString();
         const agents = this.store.listOfflineAgentsOlderThan(cutoffIso);
+        const affectedSourceIds = new Set();
         for (const agent of agents) {
+            for (const subscription of this.store.listSubscriptionsForAgent(agent.agentId)) {
+                affectedSourceIds.add(subscription.sourceId);
+            }
             this.store.deleteAgent(agent.agentId, { persist: false });
             this.notificationBuffers.forEach((buffer, key) => {
                 if (key.startsWith(`${agent.agentId}:`)) {
@@ -1231,9 +1746,15 @@ class AgentInboxService {
             });
             this.inboxWatchers.delete(agent.agentId);
         }
+        for (const sourceId of affectedSourceIds) {
+            this.refreshSourceIdleState(sourceId);
+        }
         if (agents.length > 0) {
             this.store.save();
         }
+        if (agents.length > 0) {
+            this.rescheduleTimerSync();
+        }
         return { removedAgents: agents.length };
     }
     async syncAllSubscriptions() {
@@ -1268,6 +1789,18 @@ class AgentInboxService {
     }
     async syncLifecycleGc() {
         const now = Date.now();
+        if (now - this.lastLifecycleCleanupAt >= DEFAULT_GC_INTERVAL_MS) {
+            try {
+                const lifecycle = this.runLifecycleCleanupPass(now);
+                for (const sourceId of lifecycle.affectedSourceIds) {
+                    this.refreshSourceIdleState(sourceId);
+                }
+                await this.runIdleSourceCleanupPass(now);
+            }
+            catch (error) {
+                console.warn("subscription lifecycle gc failed:", error);
+            }
+        }
         if (now - this.lastOfflineAgentGcAt < DEFAULT_GC_INTERVAL_MS) {
             return;
         }
@@ -1279,8 +1812,267 @@ 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) {
+            this.store.deleteSourceIdleState(sourceId);
+            return;
+        }
+        const sourceAdapter = this.adapters.sourceAdapterFor(source.sourceType);
+        if (!sourceAdapter.pauseSource) {
+            this.store.deleteSourceIdleState(sourceId);
+            return;
+        }
+        if (source.status === "paused") {
+            this.store.deleteSourceIdleState(sourceId);
+            return;
+        }
+        const remainingSubscriptions = this.store.listSubscriptionsForSource(sourceId).length;
+        if (remainingSubscriptions > 0) {
+            this.store.deleteSourceIdleState(sourceId);
+            return;
+        }
+        const now = (0, util_1.nowIso)();
+        this.store.upsertSourceIdleState({
+            sourceId,
+            idleSince: now,
+            autoPauseAt: new Date(Date.parse(now) + DEFAULT_IDLE_SOURCE_GRACE_MS).toISOString(),
+            autoPausedAt: null,
+            updatedAt: now,
+        });
+    }
 }
 exports.AgentInboxService = AgentInboxService;
+function hasSubscriptionFieldOverride(input) {
+    if (input.trackedResourceRef != null || input.cleanupPolicy != null) {
+        return true;
+    }
+    return input.filter != null && Object.keys(input.filter).length > 0;
+}
+function buildPreviewSource(input) {
+    const sourceType = sourceTypeForPreviewRef(input.sourceRef);
+    const now = (0, util_1.nowIso)();
+    return {
+        sourceId: "__preview__",
+        sourceType,
+        sourceKey: `preview:${input.sourceRef}`,
+        configRef: input.configRef ?? null,
+        config: input.config ?? {},
+        status: "active",
+        checkpoint: null,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function sourceTypeForPreviewRef(sourceRef) {
+    if (sourceRef === "local_event" || sourceRef === "remote_source" || sourceRef === "github_repo" || sourceRef === "github_repo_ci" || sourceRef === "feishu_bot") {
+        return sourceRef;
+    }
+    if (sourceRef.startsWith("remote:")) {
+        return "remote_source";
+    }
+    throw new Error(`unknown source kind or type for preview: ${sourceRef}`);
+}
+function normalizeTrackedResourceRef(value) {
+    if (value == null) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeCleanupPolicy(input) {
+    if (!input) {
+        return { mode: "manual" };
+    }
+    if (input.mode === "manual") {
+        if ("at" in input || "gracePeriodSecs" in input) {
+            throw new Error("cleanupPolicy mode manual does not allow at or gracePeriodSecs");
+        }
+        return { mode: "manual" };
+    }
+    if (input.mode === "at") {
+        if (!isValidIsoTimestamp(input.at)) {
+            throw new Error("cleanupPolicy mode at requires a valid ISO8601 at timestamp");
+        }
+        if ("gracePeriodSecs" in input) {
+            throw new Error("cleanupPolicy mode at does not allow gracePeriodSecs");
+        }
+        return { mode: "at", at: canonicalIsoTimestamp(input.at) };
+    }
+    if (input.mode === "on_terminal") {
+        if ("at" in input) {
+            throw new Error("cleanupPolicy mode on_terminal does not allow at");
+        }
+        return {
+            mode: "on_terminal",
+            ...(input.gracePeriodSecs != null ? { gracePeriodSecs: normalizeGracePeriodSecs(input.gracePeriodSecs) } : {}),
+        };
+    }
+    if (input.mode === "on_terminal_or_at") {
+        if (!isValidIsoTimestamp(input.at)) {
+            throw new Error("cleanupPolicy mode on_terminal_or_at requires a valid ISO8601 at timestamp");
+        }
+        return {
+            mode: "on_terminal_or_at",
+            at: canonicalIsoTimestamp(input.at),
+            ...(input.gracePeriodSecs != null ? { gracePeriodSecs: normalizeGracePeriodSecs(input.gracePeriodSecs) } : {}),
+        };
+    }
+    throw new Error(`unsupported cleanup policy mode: ${input.mode ?? "unknown"}`);
+}
+function normalizeGracePeriodSecs(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error("cleanupPolicy gracePeriodSecs must be a non-negative integer");
+    }
+    return value;
+}
+function normalizeLifecycleSignal(signal, fallbackOccurredAt) {
+    const ref = typeof signal.ref === "string" ? signal.ref.trim() : "";
+    if (ref.length === 0) {
+        return null;
+    }
+    return {
+        ref,
+        terminal: signal.terminal,
+        state: signal.state ?? null,
+        result: signal.result ?? null,
+        occurredAt: normalizeLifecycleOccurredAt(signal.occurredAt, fallbackOccurredAt),
+    };
+}
+function normalizeLifecycleOccurredAt(value, fallback) {
+    if (value && isValidIsoTimestamp(value)) {
+        return value;
+    }
+    if (fallback && isValidIsoTimestamp(fallback)) {
+        return fallback;
+    }
+    return (0, util_1.nowIso)();
+}
+function lifecycleRetireAtForSignal(cleanupPolicy, signalOccurredAtMs) {
+    if (cleanupPolicy.mode === "manual" || cleanupPolicy.mode === "at") {
+        return null;
+    }
+    if (cleanupPolicy.mode === "on_terminal") {
+        return lifecycleSignalRetireAt(signalOccurredAtMs, cleanupPolicy.gracePeriodSecs ?? null);
+    }
+    return minIsoTimestamps(cleanupPolicy.at, lifecycleSignalRetireAt(signalOccurredAtMs, cleanupPolicy.gracePeriodSecs ?? null));
+}
+function lifecycleSignalRetireAt(signalOccurredAtMs, gracePeriodSecs) {
+    const graceMs = Math.max(0, gracePeriodSecs ?? 0) * 1000;
+    return new Date(signalOccurredAtMs + graceMs).toISOString();
+}
+function lifecycleDeadlineAt(cleanupPolicy) {
+    if (cleanupPolicy.mode === "at" || cleanupPolicy.mode === "on_terminal_or_at") {
+        return cleanupPolicy.at;
+    }
+    return null;
+}
+function minIsoTimestamps(left, right) {
+    return new Date(Math.min(Date.parse(left), Date.parse(right))).toISOString();
+}
+function canonicalIsoTimestamp(value) {
+    return new Date(value).toISOString();
+}
+function isValidIsoTimestamp(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.(\d{1,3}))?(Z|([+-])(\d{2}):(\d{2}))$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const fractional = match[8] ?? "";
+    const timezone = match[9];
+    const offsetSign = match[10];
+    const offsetHour = match[11] != null ? Number(match[11]) : 0;
+    const offsetMinute = match[12] != null ? Number(match[12]) : 0;
+    const millisecond = fractional.length === 0 ? 0 : Number((fractional + "000").slice(0, 3));
+    if (month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > 31 ||
+        hour > 23 ||
+        minute > 59 ||
+        second > 59 ||
+        offsetHour > 23 ||
+        offsetMinute > 59) {
+        return false;
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        return false;
+    }
+    const offsetMinutes = timezone === "Z"
+        ? 0
+        : (offsetSign === "+" ? 1 : -1) * ((offsetHour * 60) + offsetMinute);
+    const expectedTime = Date.UTC(year, month - 1, day, hour, minute, second, millisecond)
+        - (offsetMinutes * 60_000);
+    return parsed.getTime() === expectedTime;
+}
 function retentionCutoffIso(retentionMs) {
     return new Date(Date.now() - retentionMs).toISOString();
 }
@@ -1388,6 +2180,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}`;
 }
@@ -1420,3 +2215,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}`);
+    }
+}