@holon-run/agentinbox 0.1.3 → 0.2.0

package/dist/src/service.js

@@ -4,6 +4,7 @@ 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 DEFAULT_SUBSCRIPTION_POLL_LIMIT = 100;
@@ -14,9 +15,10 @@ 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 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;
@@ -30,6 +32,7 @@ class AgentInboxService {
     syncInterval = null;
     stopping = false;
     lastAckedInboxGcAt = 0;
+    lastLifecycleCleanupAt = 0;
     lastOfflineAgentGcAt = 0;
     constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher()) {
         this.store = store;
@@ -53,7 +56,7 @@ class AgentInboxService {
             void this.syncActivationDispatchStates();
             void this.runAckedInboxGcIfDue();
             void this.syncLifecycleGc();
-        }, 2_000);
+        }, DEFAULT_SYNC_INTERVAL_MS);
         await this.syncAllSubscriptions();
         await this.syncActivationDispatchStates();
         await this.runAckedInboxGcIfDue(true);
@@ -105,30 +108,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 +247,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 +262,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),
@@ -285,7 +351,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) {
@@ -346,23 +416,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 +473,7 @@ class AgentInboxService {
             startOffset: subscription.startOffset ?? null,
             startTime: subscription.startTime ?? null,
         });
+        this.store.deleteSourceIdleState(source.sourceId);
         return subscription;
     }
     async removeSubscription(subscriptionId) {
@@ -386,6 +481,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) {
@@ -598,11 +694,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 +743,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 +820,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 +921,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) {
@@ -954,6 +1103,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());
@@ -1216,10 +1366,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,6 +1468,9 @@ class AgentInboxService {
             });
             this.inboxWatchers.delete(agent.agentId);
         }
+        for (const sourceId of affectedSourceIds) {
+            this.refreshSourceIdleState(sourceId);
+        }
         if (agents.length > 0) {
             this.store.save();
         }
@@ -1268,6 +1508,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 +1531,209 @@ class AgentInboxService {
             console.warn("offline agent gc failed:", error);
         }
     }
+    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();
 }