@holon-run/agentinbox 0.6.0 → 1.0.0-beta.0

package/dist/src/service.js

@@ -9,16 +9,22 @@ 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 logging_1 = require("./logging");
+const source_hosts_1 = require("./source_hosts");
 const DEFAULT_SUBSCRIPTION_POLL_LIMIT = 100;
 const DEFAULT_ACTIVATION_WINDOW_MS = 3_000;
 const DEFAULT_ACTIVATION_MAX_ITEMS = 20;
 const DEFAULT_NOTIFY_LEASE_MS = 10 * 60 * 1000;
 const DEFAULT_NOTIFY_RETRY_MS = 5_000;
+const MAX_TERMINAL_DEFER_RETRY_MS = 5 * 60 * 1000;
 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 DEFAULT_INBOX_AGGREGATION_WINDOW_MS = 30 * 1000;
+const DEFAULT_INBOX_AGGREGATION_MAX_ITEMS = 20;
+const DEFAULT_INBOX_AGGREGATION_MAX_THREAD_AGE_MS = 24 * 60 * 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__";
@@ -43,7 +49,7 @@ class AgentInboxService {
     lastAckedInboxGcAt = 0;
     lastLifecycleCleanupAt = 0;
     lastOfflineAgentGcAt = 0;
-    constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher(), activationGate = new runtime_gate_1.DefaultActivationGate()) {
+    constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher(), activationGate, logger = new logging_1.NoopLogger(), gatingPolicy) {
         this.store = store;
         this.adapters = adapters;
         this.activationDispatcher = activationDispatcher;
@@ -52,11 +58,13 @@ class AgentInboxService {
         this.activationMaxItems = activationPolicy?.maxItems ?? DEFAULT_ACTIVATION_MAX_ITEMS;
         this.ackedRetentionMs = DEFAULT_ACKED_RETENTION_MS;
         this.terminalDispatcher = terminalDispatcher;
-        this.activationGate = activationGate;
+        this.logger = logger;
+        this.activationGate = activationGate ?? new runtime_gate_1.DefaultActivationGate(undefined, undefined, this.logger.child("gate"), gatingPolicy);
     }
     activationDispatcher;
     terminalDispatcher;
     activationGate;
+    logger;
     async start() {
         if (this.syncInterval) {
             return;
@@ -64,12 +72,14 @@ class AgentInboxService {
         this.stopping = false;
         this.syncInterval = setInterval(() => {
             void this.syncAllSubscriptions();
+            void this.syncPendingDigestThreads();
             void this.syncActivationDispatchStates();
             void this.runAckedInboxGcIfDue();
             void this.syncLifecycleGc();
         }, DEFAULT_SYNC_INTERVAL_MS);
         this.refreshTimersOnStart();
         await this.syncAllSubscriptions();
+        await this.syncPendingDigestThreads();
         await this.syncActivationDispatchStates();
         await this.runAckedInboxGcIfDue(true);
         await this.syncLifecycleGc();
@@ -99,13 +109,31 @@ class AgentInboxService {
         if (existing) {
             return existing;
         }
+        const resolved = (0, source_hosts_1.resolveSourceRegistration)(input);
         const now = (0, util_1.nowIso)();
+        let host = this.store.getSourceHostByKey(resolved.hostType, resolved.hostKey);
+        if (!host) {
+            host = {
+                hostId: (0, util_1.generateCanonicalId)("hst"),
+                hostType: resolved.hostType,
+                hostKey: resolved.hostKey,
+                configRef: input.configRef ?? null,
+                config: resolved.hostConfig,
+                status: "active",
+                createdAt: now,
+                updatedAt: now,
+            };
+            this.store.insertSourceHost(host);
+        }
         const source = {
-            sourceId: (0, util_1.generateId)("src"),
-            sourceType: input.sourceType,
+            sourceId: (0, util_1.generateCanonicalId)("src"),
+            hostId: host.hostId,
+            streamKind: resolved.streamKind,
+            streamKey: resolved.streamKey,
+            sourceType: resolved.sourceType,
             sourceKey: input.sourceKey,
             configRef: input.configRef ?? null,
-            config: input.config ?? {},
+            config: resolved.streamConfig,
             status: "active",
             checkpoint: null,
             createdAt: now,
@@ -119,6 +147,25 @@ class AgentInboxService {
     listSources() {
         return this.store.listSources();
     }
+    listHosts() {
+        return this.store.listSourceHosts();
+    }
+    getHost(hostId) {
+        const host = this.store.getSourceHost(hostId);
+        if (!host) {
+            throw new Error(`unknown host: ${hostId}`);
+        }
+        return host;
+    }
+    getHostDetails(hostId) {
+        const host = this.getHost(hostId);
+        const streams = this.store.listSources().filter((stream) => stream.hostId === hostId);
+        return {
+            host,
+            schema: this.getHostSchema(host.hostType),
+            streams,
+        };
+    }
     getSource(sourceId) {
         const source = this.store.getSource(sourceId);
         if (!source) {
@@ -146,6 +193,7 @@ class AgentInboxService {
             : fallbackSchema;
         return {
             source,
+            host: source.hostId ? this.store.getSourceHost(source.hostId) : null,
             resolvedIdentity,
             ...(resolutionError ? { resolutionError } : {}),
             schema: resolvedSchema,
@@ -157,6 +205,74 @@ class AgentInboxService {
     getSourceSchema(sourceType) {
         return (0, source_schema_1.getSourceSchema)(sourceType);
     }
+    getHostSchema(hostType) {
+        return {
+            hostType,
+            configFields: getHostConfigFields(hostType),
+            streamKinds: listHostStreamKinds(hostType),
+        };
+    }
+    registerHost(input) {
+        const existing = this.store.getSourceHostByKey(input.hostType, input.hostKey);
+        if (existing) {
+            return existing;
+        }
+        const now = (0, util_1.nowIso)();
+        const host = {
+            hostId: (0, util_1.generateCanonicalId)("hst"),
+            hostType: input.hostType,
+            hostKey: input.hostKey,
+            configRef: input.configRef ?? null,
+            config: input.config ?? {},
+            status: "active",
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.insertSourceHost(host);
+        return host;
+    }
+    registerStream(input) {
+        const host = this.getHost(input.hostId);
+        const existing = this.store.listSources().find((stream) => stream.hostId === input.hostId &&
+            stream.streamKind === input.streamKind &&
+            stream.streamKey === input.streamKey);
+        if (existing) {
+            return Promise.resolve(existing);
+        }
+        const sourceType = sourceTypeForStreamRegistration(host.hostType, input.streamKind);
+        const now = (0, util_1.nowIso)();
+        const stream = {
+            sourceId: (0, util_1.generateCanonicalId)("src"),
+            streamId: null,
+            hostId: input.hostId,
+            streamKind: input.streamKind,
+            streamKey: input.streamKey,
+            sourceType,
+            sourceKey: input.streamKey,
+            configRef: input.configRef ?? host.configRef ?? null,
+            config: input.config ?? {},
+            status: "active",
+            checkpoint: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.insertSource(stream);
+        return this.adapters.sourceAdapterFor(sourceType)
+            .ensureSource(stream)
+            .then(async () => {
+            await this.ensureStreamForSource(stream);
+            return this.getStream(stream.sourceId);
+        });
+    }
+    listStreams() {
+        return this.listSources();
+    }
+    getStream(streamId) {
+        return this.getSource(streamId);
+    }
+    getStreamDetails(streamId) {
+        return this.getSourceDetails(streamId);
+    }
     async getResolvedSourceSchema(sourceId) {
         const source = this.getSource(sourceId);
         return this.adapters.resolveSourceSchema(source);
@@ -288,9 +404,10 @@ class AgentInboxService {
     }
     registerAgent(input) {
         validateNotifyLeaseMs(input.notifyLeaseMs);
+        validateMinUnackedItems(input.minUnackedItems);
         validateTerminalRegistration(input);
         const runtimeKind = input.runtimeKind ?? "unknown";
-        const agentId = input.agentId ?? (0, terminal_1.assignedAgentIdFromContext)({
+        const agentId = input.agentId ?? this.resolveAutoAgentId({
             runtimeKind,
             runtimeSessionId: input.runtimeSessionId ?? null,
             backend: input.backend,
@@ -404,7 +521,7 @@ class AgentInboxService {
             restartRecovery: false,
         });
         const timer = {
-            scheduleId: (0, util_1.generateId)("sched"),
+            scheduleId: (0, util_1.generateCanonicalId)("sch"),
             agentId: input.agentId,
             status: nextFireAt ? "active" : "paused",
             mode: normalized.mode,
@@ -487,10 +604,11 @@ class AgentInboxService {
     addWebhookActivationTarget(agentId, input) {
         this.getAgent(agentId);
         validateNotifyLeaseMs(input.notifyLeaseMs);
+        validateMinUnackedItems(input.minUnackedItems);
         const mode = normalizeWebhookActivationMode(input.activationMode);
         const now = (0, util_1.nowIso)();
         const target = {
-            targetId: (0, util_1.generateId)("tgt"),
+            targetId: (0, util_1.generateCanonicalId)("tgt"),
             agentId,
             kind: "webhook",
             status: "active",
@@ -501,6 +619,11 @@ class AgentInboxService {
             mode,
             url: input.url,
             notifyLeaseMs: input.notifyLeaseMs ?? DEFAULT_NOTIFY_LEASE_MS,
+            minUnackedItems: input.minUnackedItems ?? null,
+            notificationPolicy: {
+                notifyLeaseMs: input.notifyLeaseMs ?? DEFAULT_NOTIFY_LEASE_MS,
+                minUnackedItems: input.minUnackedItems ?? null,
+            },
             createdAt: now,
             updatedAt: now,
             lastSeenAt: now,
@@ -619,7 +742,7 @@ class AgentInboxService {
             this.store.deleteSourceIdleState(source.sourceId);
         }
         const subscription = {
-            subscriptionId: (0, util_1.generateId)("sub"),
+            subscriptionId: (0, util_1.generateCanonicalId)("sub"),
             agentId: input.agentId,
             sourceId: input.sourceId,
             filter: input.filter ?? {},
@@ -744,15 +867,32 @@ class AgentInboxService {
         };
     }
     listInboxItems(agentId, options) {
+        return this.store.listInboxEntries(this.ensureInboxForAgent(agentId).inboxId, options);
+    }
+    listRawInboxItems(agentId, options) {
         return this.store.listInboxItems(this.ensureInboxForAgent(agentId).inboxId, options);
     }
+    getInboxAggregationPolicy(agentId) {
+        const inbox = this.ensureInboxForAgent(agentId);
+        return inboxAggregationPolicy(inbox);
+    }
+    updateInboxAggregationPolicy(agentId, input) {
+        const inbox = this.ensureInboxForAgent(agentId);
+        const updated = this.store.updateInboxAggregationPolicy(inbox.inboxId, {
+            enabled: input.enabled,
+            windowMs: input.windowMs,
+            maxItems: input.maxItems,
+            maxThreadAgeMs: input.maxThreadAgeMs,
+        });
+        return inboxAggregationPolicy(updated);
+    }
     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"),
+            sourceNativeId: (0, util_1.generateCanonicalId)("direct"),
             eventVariant: DIRECT_INBOX_EVENT_VARIANT,
             summary: summarizeDirectInboxMessage(sender),
             rawPayload: {
@@ -799,7 +939,7 @@ class AgentInboxService {
         const inbox = this.ensureInboxForAgent(agentId);
         const occurredAt = input.occurredAt ?? (0, util_1.nowIso)();
         const item = {
-            itemId: (0, util_1.generateId)("item"),
+            itemId: (0, util_1.generateCanonicalId)("itm"),
             sourceId: input.sourceId,
             sourceNativeId: input.sourceNativeId,
             eventVariant: input.eventVariant,
@@ -821,18 +961,11 @@ class AgentInboxService {
                 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 entry = this.store.createInboxItemEntry(inbox.inboxId, item, {
+            summary: input.summary,
+            subscriptionIds: [],
+        });
+        this.notifyInboxWatchers(agentId, [entry]);
         const targets = this.store.listActivationTargetsForAgent(agentId).filter((target) => target.status === "active");
         for (const target of targets) {
             this.enqueueActivationTarget(target, {
@@ -840,7 +973,7 @@ class AgentInboxService {
                 subscriptionId: null,
                 sourceId: input.sourceId,
                 summary: input.summary,
-                item: activationItem,
+                entry,
             });
         }
         return {
@@ -849,27 +982,119 @@ class AgentInboxService {
             activated: targets.length > 0,
         };
     }
+    async materializeInboxEntryForItem(input) {
+        const activationItem = activationItemFromInboxItem(input.item);
+        const policy = inboxAggregationPolicy(input.inbox);
+        if (!policy.enabled || !input.source) {
+            return [this.store.createInboxItemEntry(input.inbox.inboxId, input.item, {
+                    summary: input.summary,
+                    subscriptionIds: input.subscriptionId ? [input.subscriptionId] : [],
+                })];
+        }
+        const grouping = await this.adapters.deriveNotificationGrouping(input.source, activationItem);
+        if (!grouping?.groupable || !grouping.resourceRef || !grouping.eventFamily) {
+            return [this.store.createInboxItemEntry(input.inbox.inboxId, input.item, {
+                    summary: input.summary,
+                    subscriptionIds: input.subscriptionId ? [input.subscriptionId] : [],
+                })];
+        }
+        const groupKey = digestGroupKey(input.source.sourceId, grouping.resourceRef, grouping.eventFamily);
+        let thread = this.store.getOpenDigestThread(input.inbox.inboxId, groupKey);
+        const now = (0, util_1.nowIso)();
+        if (thread && Date.parse(thread.createdAt) + (policy.maxThreadAgeMs ?? DEFAULT_INBOX_AGGREGATION_MAX_THREAD_AGE_MS) <= Date.now()) {
+            this.store.closeDigestThread(thread.threadId, now);
+            thread = null;
+        }
+        const flushAfterAt = new Date(Date.now() + (policy.windowMs ?? DEFAULT_INBOX_AGGREGATION_WINDOW_MS)).toISOString();
+        if (!thread) {
+            thread = this.store.createDigestThread({
+                inboxId: input.inbox.inboxId,
+                sourceId: input.source.sourceId,
+                groupKey,
+                resourceRef: grouping.resourceRef,
+                eventFamily: grouping.eventFamily,
+                summary: grouping.summaryHint ?? input.summary,
+                firstItemAt: input.item.occurredAt,
+                flushAfterAt,
+                createdAt: now,
+            });
+        }
+        else {
+            thread = this.store.addItemToDigestThread(thread.threadId, input.item.itemId, input.item.occurredAt, grouping.summaryHint ?? thread.summary, flushAfterAt);
+        }
+        if (!thread || this.store.listUnackedInboxItemsForDigestThread(thread.threadId).find((entry) => entry.itemId === input.item.itemId) == null) {
+            thread = this.store.addItemToDigestThread(thread.threadId, input.item.itemId, input.item.occurredAt, grouping.summaryHint ?? thread.summary, flushAfterAt);
+        }
+        const unacked = this.store.listUnackedInboxItemsForDigestThread(thread.threadId);
+        const shouldFlush = grouping.flushClass === "immediate" || unacked.length >= (policy.maxItems ?? DEFAULT_INBOX_AGGREGATION_MAX_ITEMS);
+        if (!shouldFlush) {
+            return [];
+        }
+        const entry = await this.flushDigestThread(input.source, thread.threadId, grouping);
+        return entry ? [entry] : [];
+    }
+    async flushDigestThread(source, threadId, groupingHint) {
+        const thread = this.store.getDigestThread(threadId);
+        if (!thread || thread.status !== "open") {
+            return null;
+        }
+        const items = this.store.listUnackedInboxItemsForDigestThread(threadId);
+        if (items.length === 0) {
+            this.store.closeDigestThread(threadId, (0, util_1.nowIso)());
+            return null;
+        }
+        const activationItems = items.map((item) => activationItemFromInboxItem(item));
+        const grouping = groupingHint ?? {
+            groupable: true,
+            resourceRef: thread.resourceRef,
+            eventFamily: thread.eventFamily,
+            summaryHint: thread.summary,
+            flushClass: "normal",
+        };
+        const moduleSummary = await this.adapters.summarizeDigestThread(source, activationItems, grouping);
+        const summary = moduleSummary ?? `${items.length} ${thread.summary}`;
+        const sourceIds = uniqueSorted(items.map((item) => item.sourceId));
+        const subscriptionIds = uniqueSortedNullable(items.map((item) => typeof item.metadata.subscriptionId === "string" ? item.metadata.subscriptionId : null));
+        const firstItemAt = items[0].occurredAt;
+        const lastItemAt = items[items.length - 1].occurredAt;
+        const deliveryHandle = sharedDeliveryHandle(items);
+        return this.store.materializeDigestSnapshot({
+            threadId,
+            inboxId: thread.inboxId,
+            groupKey: thread.groupKey,
+            resourceRef: thread.resourceRef,
+            eventFamily: thread.eventFamily,
+            summary,
+            sourceIds,
+            subscriptionIds,
+            itemIds: items.map((item) => item.itemId),
+            firstItemAt,
+            lastItemAt,
+            deliveryHandleJson: deliveryHandle ? JSON.stringify(deliveryHandle) : null,
+            createdAt: (0, util_1.nowIso)(),
+        });
+    }
     watchInbox(agentId, options, onEvent) {
         const inbox = this.ensureInboxForAgent(agentId);
         const pendingItems = [];
         let started = false;
-        const emitItems = (items) => {
-            if (items.length === 0) {
+        const emitItems = (entries) => {
+            if (entries.length === 0) {
                 return;
             }
             onEvent({
                 event: "items",
                 agentId,
-                items,
+                entries,
             });
         };
         const watcher = {
-            onItems: (items) => {
+            onItems: (entries) => {
                 if (!started) {
-                    pendingItems.push(...items);
+                    pendingItems.push(...entries);
                     return;
                 }
-                emitItems(items);
+                emitItems(entries);
             },
         };
         let watchers = this.inboxWatchers.get(agentId);
@@ -880,8 +1105,8 @@ class AgentInboxService {
         watchers.add(watcher);
         let initialItems;
         try {
-            initialItems = this.store.listInboxItems(inbox.inboxId, {
-                afterItemId: options.afterItemId,
+            initialItems = this.store.listInboxEntries(inbox.inboxId, {
+                afterEntryId: options.afterEntryId,
                 includeAcked: options.includeAcked ?? false,
             });
         }
@@ -892,7 +1117,7 @@ class AgentInboxService {
             }
             throw error;
         }
-        const initialItemIds = new Set(initialItems.map((item) => item.itemId));
+        const initialItemIds = new Set(initialItems.map((item) => item.entryId));
         return {
             initialItems,
             start: () => {
@@ -900,7 +1125,7 @@ class AgentInboxService {
                     return;
                 }
                 started = true;
-                const replayItems = pendingItems.filter((item) => !initialItemIds.has(item.itemId));
+                const replayItems = pendingItems.filter((item) => !initialItemIds.has(item.entryId));
                 pendingItems.length = 0;
                 emitItems(replayItems);
             },
@@ -916,39 +1141,40 @@ class AgentInboxService {
             },
         };
     }
-    ackInboxItems(agentId, itemIds) {
+    async ackInboxItems(agentId, itemIds) {
         const inbox = this.ensureInboxForAgent(agentId);
-        const acked = this.store.ackItems(inbox.inboxId, itemIds, (0, util_1.nowIso)());
-        if (acked > 0) {
-            void this.handleInboxAckEffects(agentId);
+        const acked = this.store.ackInboxEntries(inbox.inboxId, itemIds, (0, util_1.nowIso)());
+        if (acked.ackedEntries > 0 || acked.ackedItems > 0) {
+            await this.handleInboxAckEffects(agentId);
         }
-        return { acked };
+        return { acked: acked.ackedEntries };
     }
-    ackInboxItemsThrough(agentId, itemId) {
+    async ackInboxItemsThrough(agentId, itemId) {
         const inbox = this.ensureInboxForAgent(agentId);
-        const acked = this.store.ackItemsThrough(inbox.inboxId, itemId, (0, util_1.nowIso)());
-        if (acked > 0) {
-            void this.handleInboxAckEffects(agentId);
+        const acked = this.store.ackInboxEntriesThrough(inbox.inboxId, itemId, (0, util_1.nowIso)());
+        if (acked.ackedEntries > 0 || acked.ackedItems > 0) {
+            await this.handleInboxAckEffects(agentId);
         }
-        return { acked };
+        return { acked: acked.ackedEntries };
     }
-    ackAllInboxItems(agentId) {
+    async ackAllInboxItems(agentId) {
         const inbox = this.ensureInboxForAgent(agentId);
-        const itemIds = this.store.listInboxItems(inbox.inboxId, { includeAcked: false }).map((item) => item.itemId);
-        const acked = this.store.ackItems(inbox.inboxId, itemIds, (0, util_1.nowIso)());
-        if (acked > 0) {
-            void this.handleInboxAckEffects(agentId);
+        const itemIds = this.store.listInboxEntries(inbox.inboxId, { includeAcked: false }).map((item) => item.entryId);
+        const acked = this.store.ackInboxEntries(inbox.inboxId, itemIds, (0, util_1.nowIso)());
+        if (acked.ackedEntries > 0 || acked.ackedItems > 0) {
+            await this.handleInboxAckEffects(agentId);
         }
-        return { acked };
+        return { acked: acked.ackedEntries };
     }
-    ackInbox(agentId, input) {
+    async ackInbox(agentId, input) {
         if (input.all) {
             return this.ackAllInboxItems(agentId);
         }
-        if (input.throughItemId) {
-            return this.ackInboxItemsThrough(agentId, input.throughItemId);
+        const throughEntryId = input.throughEntryId ?? null;
+        if (throughEntryId) {
+            return this.ackInboxItemsThrough(agentId, throughEntryId);
         }
-        return this.ackInboxItems(agentId, input.itemIds ?? []);
+        return this.ackInboxItems(agentId, input.entryIds ?? []);
     }
     compactInbox(agentId) {
         const inbox = this.ensureInboxForAgent(agentId);
@@ -1013,7 +1239,7 @@ class AgentInboxService {
             let matched = 0;
             let inboxItemsCreated = 0;
             let lastProcessedOffset = null;
-            const insertedItems = [];
+            const insertedEntries = [];
             const lifecycleSignals = new Map();
             try {
                 for (const event of batch.events) {
@@ -1031,13 +1257,18 @@ class AgentInboxService {
                     }
                     matched += 1;
                     const item = {
-                        itemId: (0, util_1.generateId)("item"),
+                        itemId: (0, util_1.generateCanonicalId)("itm"),
                         sourceId: event.sourceId,
                         sourceNativeId: event.sourceNativeId,
                         eventVariant: event.eventVariant,
                         inboxId: inbox.inboxId,
                         occurredAt: event.occurredAt,
-                        metadata: { ...event.metadata, matchReason: match.reason, agentId: subscription.agentId },
+                        metadata: {
+                            ...event.metadata,
+                            matchReason: match.reason,
+                            agentId: subscription.agentId,
+                            subscriptionId: subscription.subscriptionId,
+                        },
                         rawPayload: event.rawPayload,
                         deliveryHandle: event.deliveryHandle,
                         ackedAt: null,
@@ -1047,32 +1278,31 @@ class AgentInboxService {
                         continue;
                     }
                     inboxItemsCreated += 1;
-                    insertedItems.push(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,
-                    };
-                    for (const target of targets) {
-                        this.enqueueActivationTarget(target, {
-                            agentId: subscription.agentId,
-                            subscriptionId: subscription.subscriptionId,
-                            sourceId: source.sourceId,
-                            summary: summarizeSourceEvent(source.sourceType, source.sourceKey, event.eventVariant),
-                            item: activationItem,
-                        });
+                    const entries = await this.materializeInboxEntryForItem({
+                        agentId: subscription.agentId,
+                        inbox,
+                        source,
+                        subscriptionId: subscription.subscriptionId,
+                        item,
+                        summary: summarizeSourceEvent(source.sourceType, source.sourceKey, event.eventVariant),
+                    });
+                    insertedEntries.push(...entries);
+                    for (const entry of entries) {
+                        for (const target of targets) {
+                            this.enqueueActivationTarget(target, {
+                                agentId: subscription.agentId,
+                                subscriptionId: subscription.subscriptionId,
+                                sourceId: source.sourceId,
+                                summary: entry.summary,
+                                entry,
+                            });
+                        }
                     }
                 }
             }
             catch (error) {
-                if (insertedItems.length > 0) {
-                    this.notifyInboxWatchers(subscription.agentId, insertedItems);
+                if (insertedEntries.length > 0) {
+                    this.notifyInboxWatchers(subscription.agentId, insertedEntries);
                 }
                 if (lastProcessedOffset != null) {
                     await this.backend.commit({
@@ -1082,8 +1312,8 @@ class AgentInboxService {
                 }
                 throw error;
             }
-            if (insertedItems.length > 0) {
-                this.notifyInboxWatchers(subscription.agentId, insertedItems);
+            if (insertedEntries.length > 0) {
+                this.notifyInboxWatchers(subscription.agentId, insertedEntries);
             }
             if (lastProcessedOffset != null) {
                 await this.backend.commit({
@@ -1110,8 +1340,9 @@ class AgentInboxService {
     }
     async sendDelivery(request) {
         const handle = resolveDeliveryHandle(request);
+        const source = resolveDeliverySource(this.store, request.sourceId, handle);
         const attempt = {
-            deliveryId: (0, util_1.generateId)("dlv"),
+            deliveryId: (0, util_1.generateCanonicalId)("dlv"),
             provider: handle.provider,
             surface: handle.surface,
             targetRef: handle.targetRef,
@@ -1122,12 +1353,52 @@ class AgentInboxService {
             status: "accepted",
             createdAt: (0, util_1.nowIso)(),
         };
-        const adapter = this.adapters.deliveryAdapterFor(handle.provider);
-        const result = await adapter.send(request, attempt);
+        const result = source
+            ? await this.sendCanonicalDeliveryViaModule(source, handle, request.payload, attempt)
+            : await this.adapters.deliveryAdapterFor(handle.provider).send(request, attempt);
         const storedAttempt = { ...attempt, status: result.status };
         this.store.insertDelivery(storedAttempt);
         return { ...storedAttempt, note: result.note };
     }
+    async listDeliveryActions(request) {
+        const handle = resolveDeliveryHandle(request);
+        const source = resolveDeliverySource(this.store, request.sourceId, handle);
+        const operations = await this.adapters.listDeliveryOperations(source, handle);
+        return {
+            sourceId: source?.sourceId ?? null,
+            handle,
+            operations,
+        };
+    }
+    async invokeDelivery(request) {
+        const handle = resolveDeliveryHandle(request);
+        const source = resolveDeliverySource(this.store, request.sourceId, handle);
+        const attempt = {
+            deliveryId: (0, util_1.generateCanonicalId)("dlv"),
+            provider: handle.provider,
+            surface: handle.surface,
+            targetRef: handle.targetRef,
+            threadRef: handle.threadRef ?? null,
+            replyMode: handle.replyMode ?? null,
+            kind: request.operation,
+            payload: request.input,
+            status: "accepted",
+            createdAt: (0, util_1.nowIso)(),
+        };
+        const result = await this.adapters.invokeDeliveryOperation(source, handle, request.operation, request.input, attempt);
+        const storedAttempt = { ...attempt, status: result.status };
+        this.store.insertDelivery(storedAttempt);
+        return { ...storedAttempt, note: result.note, operation: request.operation };
+    }
+    async sendCanonicalDeliveryViaModule(source, handle, payload, attempt) {
+        const operations = await this.adapters.listDeliveryOperations(source, handle);
+        const canonicalOperation = operations.find((operation) => operation.canonicalTextAlias);
+        if (!canonicalOperation) {
+            throw new Error(`deliver send is not supported for ${handle.provider}/${handle.surface}; use deliver invoke`);
+        }
+        const input = payload.text != null ? { ...payload, body: String(payload.text) } : payload;
+        return this.adapters.invokeDeliveryOperation(source, handle, canonicalOperation.name, input, attempt);
+    }
     status() {
         return {
             retention: {
@@ -1160,7 +1431,7 @@ class AgentInboxService {
             return existing;
         }
         const inbox = {
-            inboxId: (0, backend_1.defaultInboxIdForAgent)(agentId),
+            inboxId: (0, util_1.generateCanonicalId)("inb"),
             ownerAgentId: agentId,
             createdAt: (0, util_1.nowIso)(),
         };
@@ -1188,7 +1459,7 @@ class AgentInboxService {
     async ensureStreamForSource(source) {
         return this.backend.ensureStream({
             sourceId: source.sourceId,
-            streamKey: (0, backend_1.streamKeyForSource)(source.sourceType, source.sourceKey),
+            streamKey: (0, backend_1.streamKeyForSource)(source.sourceId),
             backend: "sqlite",
         });
     }
@@ -1247,6 +1518,29 @@ class AgentInboxService {
             watcher.onItems(items);
         }
     }
+    resolveAutoAgentId(input) {
+        for (let attempt = 0; attempt < 32; attempt += 1) {
+            const candidate = (0, terminal_1.assignedAgentIdFromContext)({
+                runtimeKind: input.runtimeKind,
+                runtimeSessionId: input.runtimeSessionId,
+                backend: input.backend,
+                tmuxPaneId: input.tmuxPaneId,
+                itermSessionId: input.itermSessionId,
+                tty: input.tty,
+            }, attempt);
+            const existing = this.store.getAgent(candidate);
+            if (!existing) {
+                return candidate;
+            }
+            const targets = this.store
+                .listActivationTargetsForAgent(candidate)
+                .filter((target) => target.kind === "terminal");
+            if (targets.length === 0 || targets.some((target) => isSameTerminalIdentity(target, input))) {
+                return candidate;
+            }
+        }
+        throw new Error("unable to derive a unique agentId from terminal context");
+    }
     handleAgentRegistrationConflicts(agentId, input) {
         const currentTarget = findExistingTerminalActivationTarget(this.store, input);
         if (currentTarget && currentTarget.agentId !== agentId) {
@@ -1272,6 +1566,7 @@ class AgentInboxService {
     upsertTerminalActivationTarget(agentId, input, now) {
         const existing = findExistingTerminalActivationTarget(this.store, input);
         if (existing) {
+            const existingPolicy = notificationPolicyForTarget(existing);
             const target = this.store.updateTerminalActivationTargetHeartbeat(existing.targetId, {
                 runtimeKind: input.runtimeKind ?? "unknown",
                 runtimeSessionId: input.runtimeSessionId ?? null,
@@ -1280,6 +1575,8 @@ class AgentInboxService {
                 tty: input.tty ?? null,
                 termProgram: input.termProgram ?? null,
                 itermSessionId: input.itermSessionId ?? null,
+                notifyLeaseMs: input.notifyLeaseMs ?? existingPolicy.notifyLeaseMs,
+                minUnackedItems: input.minUnackedItems ?? existingPolicy.minUnackedItems ?? null,
                 updatedAt: now,
                 lastSeenAt: now,
             });
@@ -1290,7 +1587,7 @@ class AgentInboxService {
             return target;
         }
         const target = {
-            targetId: (0, util_1.generateId)("tgt"),
+            targetId: (0, util_1.generateCanonicalId)("tgt"),
             agentId,
             kind: "terminal",
             status: "active",
@@ -1300,6 +1597,11 @@ class AgentInboxService {
             lastError: null,
             mode: "agent_prompt",
             notifyLeaseMs: input.notifyLeaseMs ?? DEFAULT_NOTIFY_LEASE_MS,
+            minUnackedItems: input.minUnackedItems ?? null,
+            notificationPolicy: {
+                notifyLeaseMs: input.notifyLeaseMs ?? DEFAULT_NOTIFY_LEASE_MS,
+                minUnackedItems: input.minUnackedItems ?? null,
+            },
             runtimeKind: input.runtimeKind ?? "unknown",
             runtimeSessionId: input.runtimeSessionId ?? null,
             runtimePid: input.runtimePid ?? null,
@@ -1333,7 +1635,7 @@ class AgentInboxService {
             subscriptionId: input.subscriptionId,
             sourceId: input.sourceId,
             summary: input.summary,
-            item: input.item,
+            entry: input.entry,
         });
         if (!buffer.timer && !buffer.inFlight) {
             buffer.timer = setTimeout(() => {
@@ -1406,44 +1708,84 @@ class AgentInboxService {
         const entries = buffer.pending.splice(0, buffer.pending.length);
         try {
             const state = this.store.getActivationDispatchState(buffer.agentId, buffer.targetId);
-            if (!state) {
+            const shouldAttemptDispatch = !state || (state.status === "dirty" && state.leaseExpiresAt == null);
+            if (shouldAttemptDispatch) {
                 const inbox = this.ensureInboxForAgent(buffer.agentId);
-                const unackedItems = this.store.listInboxItems(inbox.inboxId, { includeAcked: false }).map((item) => ({
-                    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 unackedItems = this.store.listInboxEntries(inbox.inboxId, { includeAcked: false });
                 const dispatched = await this.dispatchActivationTarget({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
-                    newItemCount: entries.length,
+                    newItemCount: state ? state.pendingNewItemCount + entries.length : entries.length,
                     totalUnackedCount: unackedItems.length,
-                    summary: latestSummary(entries),
-                    subscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
-                    sourceIds: uniqueSorted(entries.map((entry) => entry.sourceId)),
-                    items: unackedItems,
+                    summary: state ? latestSummary(entries) ?? state.pendingSummary : latestSummary(entries),
+                    subscriptionIds: state
+                        ? uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)])
+                        : uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
+                    sourceIds: state
+                        ? uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)])
+                        : uniqueSorted(entries.map((entry) => entry.sourceId)),
+                    entries: unackedItems,
                 });
                 if (dispatched === "retryable_failure") {
-                    this.upsertDirtyDispatchState(buffer.agentId, buffer.targetId, entries);
+                    if (state && state.status === "dirty" && state.leaseExpiresAt == null) {
+                        this.store.upsertActivationDispatchState({
+                            agentId: buffer.agentId,
+                            targetId: buffer.targetId,
+                            status: "dirty",
+                            leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+                            lastNotifiedFingerprint: state.lastNotifiedFingerprint,
+                            deferReason: null,
+                            deferAttempts: 0,
+                            firstDeferredAt: null,
+                            lastDeferredAt: null,
+                            pendingFingerprint: null,
+                            pendingNewItemCount: state.pendingNewItemCount + entries.length,
+                            pendingSummary: latestSummary(entries) ?? state.pendingSummary,
+                            pendingSubscriptionIds: uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
+                            pendingSourceIds: uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]),
+                            updatedAt: (0, util_1.nowIso)(),
+                        });
+                    }
+                    else {
+                        this.upsertDirtyDispatchState(buffer.agentId, buffer.targetId, entries);
+                    }
                 }
             }
             else {
+                const mergedNewItemCount = state.pendingNewItemCount + entries.length;
+                const mergedSummary = latestSummary(entries) ?? state.pendingSummary;
+                const mergedSubscriptionIds = uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]);
+                const mergedSourceIds = uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]);
+                let deferReason = state.deferReason;
+                let deferAttempts = state.deferAttempts;
+                let firstDeferredAt = state.firstDeferredAt;
+                let lastDeferredAt = state.lastDeferredAt;
+                let pendingFingerprint = state.pendingFingerprint;
+                let leaseExpiresAt = state.leaseExpiresAt;
+                if (state.status === "dirty" && state.leaseExpiresAt != null && state.deferReason) {
+                    pendingFingerprint = null;
+                    this.logger.debug("activation.defer_pending_marked_stale", {
+                        agentId: buffer.agentId,
+                        targetId: buffer.targetId,
+                        deferReason: state.deferReason,
+                        deferAttempts: state.deferAttempts,
+                    });
+                }
                 this.store.upsertActivationDispatchState({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
                     status: "dirty",
-                    leaseExpiresAt: state.leaseExpiresAt,
+                    leaseExpiresAt,
                     lastNotifiedFingerprint: state.lastNotifiedFingerprint,
-                    pendingNewItemCount: state.pendingNewItemCount + entries.length,
-                    pendingSummary: latestSummary(entries) ?? state.pendingSummary,
-                    pendingSubscriptionIds: uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
-                    pendingSourceIds: uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]),
+                    deferReason,
+                    deferAttempts,
+                    firstDeferredAt,
+                    lastDeferredAt,
+                    pendingFingerprint,
+                    pendingNewItemCount: mergedNewItemCount,
+                    pendingSummary: mergedSummary,
+                    pendingSubscriptionIds: mergedSubscriptionIds,
+                    pendingSourceIds: mergedSourceIds,
                     updatedAt: (0, util_1.nowIso)(),
                 });
             }
@@ -1471,27 +1813,63 @@ class AgentInboxService {
         }
     }
     async handleInboxAckEffects(agentId) {
+        await this.reconcileDigestThreadsForInbox(this.ensureInboxForAgent(agentId).inboxId);
         const states = this.store.listActivationDispatchStatesForAgent(agentId);
         for (const state of states) {
             await this.maybeDispatchActivationTarget(agentId, state.targetId, "ack");
         }
     }
+    async reconcileDigestThreadsForInbox(inboxId) {
+        for (const thread of this.store.listOpenDigestThreadsForInbox(inboxId)) {
+            const source = this.store.getSource(thread.sourceId);
+            if (!source) {
+                this.store.closeDigestThread(thread.threadId, (0, util_1.nowIso)());
+                continue;
+            }
+            const items = this.store.listUnackedInboxItemsForDigestThread(thread.threadId);
+            if (items.length === 0) {
+                this.store.closeDigestThread(thread.threadId, (0, util_1.nowIso)());
+                continue;
+            }
+            const head = thread.latestEntryId != null ? this.store.getInboxEntry(thread.latestEntryId) : null;
+            const currentIds = items.map((item) => item.itemId);
+            const headIds = head?.itemIds ?? [];
+            if (!sameStringArray(currentIds, headIds)) {
+                await this.flushDigestThread(source, thread.threadId);
+            }
+        }
+    }
     async maybeDispatchActivationTarget(agentId, targetId, reason) {
         const state = this.store.getActivationDispatchState(agentId, targetId);
         if (!state) {
             return;
         }
+        const target = this.getActivationTarget(targetId);
         const inbox = this.ensureInboxForAgent(agentId);
-        const unacked = this.store.countInboxItems(inbox.inboxId, false);
+        const unacked = this.store.listInboxEntries(inbox.inboxId, { includeAcked: false }).length;
         if (unacked === 0) {
             this.store.deleteActivationDispatchState(agentId, targetId);
             return;
         }
+        if (!meetsNotificationThreshold(notificationPolicyForTarget(target), unacked)) {
+            this.store.upsertActivationDispatchState({
+                ...state,
+                status: "dirty",
+                leaseExpiresAt: null,
+                deferReason: null,
+                deferAttempts: 0,
+                firstDeferredAt: null,
+                lastDeferredAt: null,
+                pendingFingerprint: null,
+                pendingNewItemCount: state.pendingNewItemCount > 0 ? state.pendingNewItemCount : unacked,
+                updatedAt: (0, util_1.nowIso)(),
+            });
+            return;
+        }
         if (reason === "ack" && state.status !== "dirty") {
             return;
         }
         if (reason === "lease" && state.status === "notified") {
-            const target = this.getActivationTarget(targetId);
             if (target.kind !== "terminal") {
                 // Webhook targets keep the existing lease-based behavior.
             }
@@ -1512,17 +1890,7 @@ class AgentInboxService {
             summary: state.pendingSummary,
             subscriptionIds: state.pendingSubscriptionIds,
             sourceIds: state.pendingSourceIds,
-            items: this.store.listInboxItems(inbox.inboxId, { includeAcked: false }).map((item) => ({
-                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,
-            })),
+            entries: this.store.listInboxEntries(inbox.inboxId, { includeAcked: false }),
         });
         if (dispatched === "offline") {
             this.store.deleteActivationDispatchState(agentId, targetId);
@@ -1533,6 +1901,11 @@ class AgentInboxService {
                 ...state,
                 status: "dirty",
                 leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+                deferReason: null,
+                deferAttempts: 0,
+                firstDeferredAt: null,
+                lastDeferredAt: null,
+                pendingFingerprint: null,
                 updatedAt: (0, util_1.nowIso)(),
             });
         }
@@ -1545,23 +1918,94 @@ class AgentInboxService {
         const state = this.store.getActivationDispatchState(input.agentId, input.targetId);
         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);
+        const totalUnackedCount = input.totalUnackedCount ?? this.store.listInboxEntries(inbox.inboxId, { includeAcked: false }).length;
+        const notificationPolicy = notificationPolicyForTarget(target);
+        if (!meetsNotificationThreshold(notificationPolicy, totalUnackedCount)) {
+            this.logger.debug("activation.dispatch_suppressed", {
+                agentId: input.agentId,
+                targetId: target.targetId,
+                reason: "min_unacked_items",
+                totalUnackedCount,
+                minUnackedItems: notificationPolicy.minUnackedItems ?? null,
+            });
+            this.store.upsertActivationDispatchState({
+                agentId: input.agentId,
+                targetId: input.targetId,
+                status: "dirty",
+                leaseExpiresAt: null,
+                lastNotifiedFingerprint: state?.lastNotifiedFingerprint ?? null,
+                deferReason: null,
+                deferAttempts: 0,
+                firstDeferredAt: null,
+                lastDeferredAt: null,
+                pendingFingerprint: null,
+                pendingNewItemCount: input.newItemCount,
+                pendingSummary: input.summary,
+                pendingSubscriptionIds: uniqueSortedNullable(input.subscriptionIds),
+                pendingSourceIds: uniqueSorted(input.sourceIds),
+                updatedAt: (0, util_1.nowIso)(),
+            });
+            return "suppressed";
+        }
         let terminalPrompt = null;
+        let terminalPromptFingerprint = null;
         try {
             if (target.kind === "terminal") {
                 const gate = await this.activationGate.evaluate(target);
+                this.logger.debug("activation.gate_decision", {
+                    agentId: input.agentId,
+                    targetId: target.targetId,
+                    runtimeKind: target.runtimeKind,
+                    backend: target.backend,
+                    outcome: gate.outcome,
+                    reason: gate.reason,
+                });
                 if (gate.outcome === "offline") {
+                    this.logger.info("activation.target_offline", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        reason: gate.reason,
+                        transition: "runtime_gate",
+                    });
                     this.markActivationTargetOffline(target.targetId, `runtime gate: ${gate.reason}`);
                     this.reconcileAgentStatus(target.agentId);
                     return "offline";
                 }
+                const reminder = await this.buildTerminalReminder(target, inbox.inboxId, totalUnackedCount, input.summary, input.entries);
+                const prompt = reminder.prompt;
+                const promptFingerprint = reminder.fingerprint;
+                terminalPrompt = prompt;
+                terminalPromptFingerprint = promptFingerprint;
                 if (gate.outcome === "defer") {
+                    const deferReason = toActivationDispatchDeferReason(gate.reason, this.logger);
+                    const hasExistingDeferred = state?.deferReason != null;
+                    const deferAttempts = hasExistingDeferred ? state.deferAttempts + 1 : 1;
+                    const deferredAt = (0, util_1.nowIso)();
+                    const retryMs = terminalDeferRetryMs(deferAttempts);
+                    const existingLeaseMs = state?.leaseExpiresAt == null ? Number.NaN : Date.parse(state.leaseExpiresAt);
+                    const candidateLeaseMs = Date.now() + retryMs;
+                    const nextLeaseMs = Number.isNaN(existingLeaseMs)
+                        ? candidateLeaseMs
+                        : Math.max(existingLeaseMs, candidateLeaseMs);
+                    this.logger.debug("activation.dispatch_deferred", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        reason: deferReason,
+                        retryMs,
+                        deferAttempts,
+                        pendingFingerprint: promptFingerprint,
+                    });
                     this.store.upsertActivationDispatchState({
                         agentId: input.agentId,
                         targetId: input.targetId,
                         status: "dirty",
-                        leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+                        leaseExpiresAt: new Date(nextLeaseMs).toISOString(),
                         lastNotifiedFingerprint: state?.lastNotifiedFingerprint ?? null,
+                        deferReason,
+                        deferAttempts,
+                        firstDeferredAt: state?.firstDeferredAt ?? deferredAt,
+                        lastDeferredAt: deferredAt,
+                        pendingFingerprint: promptFingerprint,
                         pendingNewItemCount: input.newItemCount,
                         pendingSummary: input.summary,
                         pendingSubscriptionIds: uniqueSortedNullable(input.subscriptionIds),
@@ -1570,36 +2014,32 @@ class AgentInboxService {
                     });
                     return "deferred";
                 }
-                let preview = null;
-                if (totalUnackedCount === 1 && input.items.length === 1) {
-                    const singleItem = input.items[0];
-                    const source = this.store.getSource(singleItem.sourceId);
-                    if (source) {
-                        try {
-                            const sourcePreview = await this.adapters.deriveInlinePreview(source, singleItem);
-                            preview = typeof sourcePreview === "string" ? (0, terminal_1.normalizeInlinePreviewText)(sourcePreview) : null;
-                        }
-                        catch {
-                            preview = null;
-                        }
-                    }
-                    preview ??= (0, terminal_1.deriveInlineItemPreview)(singleItem, input.summary);
+                if (state?.pendingFingerprint && state.pendingFingerprint !== promptFingerprint) {
+                    this.logger.debug("activation.defer_pending_revalidated", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        previousFingerprint: state.pendingFingerprint,
+                        currentFingerprint: promptFingerprint,
+                    });
                 }
-                const prompt = (0, terminal_1.renderAgentPrompt)({
-                    inboxId: inbox.inboxId,
-                    totalUnackedCount,
-                    summary: input.summary,
-                    preview,
-                });
-                terminalPrompt = prompt;
-                const promptFingerprint = terminalReminderFingerprint(prompt, input.items);
-                if (state?.status === "dirty" && state.lastNotifiedFingerprint === promptFingerprint) {
+                if (state?.lastNotifiedFingerprint === promptFingerprint) {
+                    this.logger.debug("activation.dispatch_suppressed", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        reason: "unchanged_terminal_prompt",
+                        status: state.status,
+                    });
                     this.store.upsertActivationDispatchState({
                         agentId: input.agentId,
                         targetId: input.targetId,
                         status: "notified",
                         leaseExpiresAt: new Date(Date.now() + target.notifyLeaseMs).toISOString(),
                         lastNotifiedFingerprint: promptFingerprint,
+                        deferReason: null,
+                        deferAttempts: 0,
+                        firstDeferredAt: null,
+                        lastDeferredAt: null,
+                        pendingFingerprint: null,
                         pendingNewItemCount: 0,
                         pendingSummary: null,
                         pendingSubscriptionIds: [],
@@ -1608,21 +2048,39 @@ class AgentInboxService {
                     });
                     return "suppressed";
                 }
+                this.logger.debug("activation.terminal_dispatch_start", {
+                    agentId: input.agentId,
+                    targetId: target.targetId,
+                    totalUnackedCount,
+                    newItemCount: input.newItemCount,
+                    sourceIds: input.sourceIds,
+                    subscriptionIds: input.subscriptionIds,
+                });
                 await this.terminalDispatcher.dispatch(target, prompt);
+                this.logger.debug("activation.terminal_dispatch_succeeded", {
+                    agentId: input.agentId,
+                    targetId: target.targetId,
+                });
             }
             else {
                 const activation = {
                     kind: "agentinbox.activation",
-                    activationId: (0, util_1.generateId)("act"),
+                    activationId: (0, util_1.generateCanonicalId)("act"),
                     agentId: input.agentId,
                     inboxId: inbox.inboxId,
                     targetId: target.targetId,
                     targetKind: target.kind,
                     subscriptionIds: input.subscriptionIds,
                     sourceIds: input.sourceIds,
+                    newEntryCount: input.entries.length,
                     newItemCount: input.newItemCount,
                     summary,
-                    items: target.mode === "activation_with_items" && input.items.length > 0 ? input.items : undefined,
+                    items: target.mode === "activation_with_items"
+                        ? input.entries
+                            .filter((entry) => entry.kind === "item")
+                            .map((entry) => entry.item)
+                        : undefined,
+                    entries: target.mode === "activation_with_items" && input.entries.length > 0 ? input.entries : undefined,
                     createdAt: (0, util_1.nowIso)(),
                     deliveredAt: null,
                 };
@@ -1637,8 +2095,13 @@ class AgentInboxService {
                 status: "notified",
                 leaseExpiresAt: new Date(Date.now() + target.notifyLeaseMs).toISOString(),
                 lastNotifiedFingerprint: target.kind === "terminal"
-                    ? terminalReminderFingerprint(terminalPrompt ?? "", input.items)
+                    ? terminalPromptFingerprint
                     : state?.lastNotifiedFingerprint ?? null,
+                deferReason: null,
+                deferAttempts: 0,
+                firstDeferredAt: null,
+                lastDeferredAt: null,
+                pendingFingerprint: null,
                 pendingNewItemCount: 0,
                 pendingSummary: null,
                 pendingSubscriptionIds: [],
@@ -1648,11 +2111,28 @@ class AgentInboxService {
             return "dispatched";
         }
         catch (error) {
-            console.warn(`activation target dispatch failed for ${target.targetId}:`, error);
             const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn("activation.dispatch_failed", {
+                agentId: input.agentId,
+                targetId: target.targetId,
+                targetKind: target.kind,
+                error,
+                message,
+            });
             if (target.kind === "terminal") {
                 const exists = await this.terminalDispatcher.probe(target);
+                this.logger.debug("activation.terminal_probe_after_failure", {
+                    agentId: input.agentId,
+                    targetId: target.targetId,
+                    exists,
+                });
                 if (!exists) {
+                    this.logger.info("activation.target_offline", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        reason: message,
+                        transition: "dispatch_probe",
+                    });
                     this.markActivationTargetOffline(target.targetId, message);
                     this.reconcileAgentStatus(target.agentId);
                     return "offline";
@@ -1669,6 +2149,11 @@ class AgentInboxService {
             status: "dirty",
             leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
             lastNotifiedFingerprint: this.store.getActivationDispatchState(agentId, targetId)?.lastNotifiedFingerprint ?? null,
+            deferReason: null,
+            deferAttempts: 0,
+            firstDeferredAt: null,
+            lastDeferredAt: null,
+            pendingFingerprint: null,
             pendingNewItemCount: entries.length,
             pendingSummary: latestSummary(entries),
             pendingSubscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
@@ -1676,6 +2161,33 @@ class AgentInboxService {
             updatedAt: (0, util_1.nowIso)(),
         });
     }
+    async buildTerminalReminder(target, inboxId, totalUnackedCount, summary, entries) {
+        let preview = null;
+        if (totalUnackedCount === 1 && entries.length === 1 && entries[0]?.kind === "item") {
+            const singleItem = entries[0].item;
+            const source = this.store.getSource(singleItem.sourceId);
+            if (source) {
+                try {
+                    const sourcePreview = await this.adapters.deriveInlinePreview(source, singleItem);
+                    preview = typeof sourcePreview === "string" ? (0, terminal_1.normalizeInlinePreviewText)(sourcePreview) : null;
+                }
+                catch {
+                    preview = null;
+                }
+            }
+            preview ??= (0, terminal_1.deriveInlineItemPreview)(singleItem, summary);
+        }
+        const prompt = (0, terminal_1.renderAgentPrompt)({
+            inboxId,
+            totalUnackedCount,
+            summary,
+            preview,
+        });
+        return {
+            prompt,
+            fingerprint: terminalReminderFingerprint(prompt, entries),
+        };
+    }
     detectDirectInboxSender(env) {
         try {
             const detected = (0, terminal_1.detectTerminalContext)(env);
@@ -1949,6 +2461,43 @@ class AgentInboxService {
             }
         }
     }
+    async syncPendingDigestThreads(force = false) {
+        const now = (0, util_1.nowIso)();
+        const threads = force
+            ? this.store.listOpenDigestThreads()
+            : this.store.listDueDigestThreads(now);
+        for (const thread of threads) {
+            try {
+                const source = this.store.getSource(thread.sourceId);
+                if (!source) {
+                    this.store.closeDigestThread(thread.threadId, now);
+                    continue;
+                }
+                const entry = await this.flushDigestThread(source, thread.threadId);
+                if (!entry) {
+                    continue;
+                }
+                const inbox = this.store.getInbox(thread.inboxId);
+                if (!inbox) {
+                    continue;
+                }
+                this.notifyInboxWatchers(inbox.ownerAgentId, [entry]);
+                const targets = this.store.listActivationTargetsForAgent(inbox.ownerAgentId).filter((target) => target.status === "active");
+                for (const target of targets) {
+                    this.enqueueActivationTarget(target, {
+                        agentId: inbox.ownerAgentId,
+                        subscriptionId: null,
+                        sourceId: thread.sourceId,
+                        summary: entry.summary,
+                        entry,
+                    });
+                }
+            }
+            catch (error) {
+                console.warn(`digest thread flush failed for ${thread.threadId}:`, error);
+            }
+        }
+    }
     async syncLifecycleGc() {
         const now = Date.now();
         if (now - this.lastLifecycleCleanupAt >= DEFAULT_GC_INTERVAL_MS) {
@@ -2253,6 +2802,29 @@ function resolveDeliveryHandle(request) {
         replyMode: request.replyMode ?? null,
     };
 }
+function resolveDeliverySource(store, sourceId, handle) {
+    if (!sourceId) {
+        return null;
+    }
+    const source = store.getSource(sourceId);
+    if (!source) {
+        throw new Error(`unknown source: ${sourceId}`);
+    }
+    const expectedProvider = providerForSourceType(source.sourceType);
+    if (expectedProvider && expectedProvider !== handle.provider) {
+        throw new Error(`source ${sourceId} does not match delivery provider ${handle.provider}`);
+    }
+    return source;
+}
+function providerForSourceType(sourceType) {
+    if (sourceType === "github_repo") {
+        return "github";
+    }
+    if (sourceType === "feishu_bot") {
+        return "feishu";
+    }
+    return null;
+}
 class ActivationDispatcher {
     async dispatch(targetUrl, activation) {
         try {
@@ -2295,6 +2867,76 @@ function validateNotifyLeaseMs(value) {
         throw new Error("notifyLeaseMs must be a positive integer");
     }
 }
+function validateMinUnackedItems(value) {
+    if (value == null) {
+        return;
+    }
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error("minUnackedItems must be a positive integer");
+    }
+}
+function notificationPolicyForTarget(target) {
+    return target.notificationPolicy ?? {
+        notifyLeaseMs: target.notifyLeaseMs,
+        minUnackedItems: target.minUnackedItems ?? null,
+    };
+}
+function inboxAggregationPolicy(inbox) {
+    return {
+        enabled: inbox.aggregationEnabled ?? false,
+        windowMs: inbox.aggregationWindowMs ?? DEFAULT_INBOX_AGGREGATION_WINDOW_MS,
+        maxItems: inbox.aggregationMaxItems ?? DEFAULT_INBOX_AGGREGATION_MAX_ITEMS,
+        maxThreadAgeMs: inbox.aggregationMaxThreadAgeMs ?? DEFAULT_INBOX_AGGREGATION_MAX_THREAD_AGE_MS,
+    };
+}
+function meetsNotificationThreshold(policy, totalUnackedCount) {
+    if (policy.minUnackedItems == null) {
+        return true;
+    }
+    return totalUnackedCount >= policy.minUnackedItems;
+}
+function activationItemFromInboxItem(item) {
+    return {
+        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,
+    };
+}
+function digestGroupKey(sourceId, resourceRef, eventFamily) {
+    return `${sourceId}::${resourceRef}::${eventFamily}`;
+}
+function sameStringArray(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] !== right[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+function sameDeliveryHandle(left, right) {
+    return JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
+}
+function sharedDeliveryHandle(items) {
+    const first = items[0]?.deliveryHandle ?? null;
+    if (!first) {
+        return null;
+    }
+    for (const item of items.slice(1)) {
+        if (!sameDeliveryHandle(first, item.deliveryHandle ?? null)) {
+            return null;
+        }
+    }
+    return first;
+}
 function normalizeWebhookActivationMode(mode) {
     const resolved = mode ?? "activation_only";
     if (!WEBHOOK_ACTIVATION_MODES.has(resolved)) {
@@ -2368,11 +3010,26 @@ function terminalReminderFingerprint(prompt, items) {
     const payload = JSON.stringify({
         prompt,
         itemIds: items
-            .map((item) => item.itemId)
+            .map((item) => item.entryId)
             .sort((left, right) => left.localeCompare(right)),
     });
     return (0, node_crypto_1.createHash)("sha256").update(payload).digest("hex");
 }
+function toActivationDispatchDeferReason(reason, logger) {
+    if (reason === "terminal_recently_active" || reason === "terminal_busy") {
+        return reason;
+    }
+    logger?.warn("activation.unexpected_defer_reason", {
+        reason,
+        fallback: reason,
+    });
+    return reason;
+}
+function terminalDeferRetryMs(attempts) {
+    const normalizedAttempts = Math.max(1, attempts);
+    const multiplier = 2 ** (normalizedAttempts - 1);
+    return Math.min(DEFAULT_NOTIFY_RETRY_MS * multiplier, MAX_TERMINAL_DEFER_RETRY_MS);
+}
 function summarizeSourceEvent(sourceType, sourceKey, eventVariant) {
     if (sourceType === "github_repo_ci") {
         const parts = eventVariant.split(".");
@@ -2691,3 +3348,48 @@ function weekdayToNumber(value) {
             throw new Error(`unsupported weekday: ${value}`);
     }
 }
+function listHostStreamKinds(hostType) {
+    switch (hostType) {
+        case "github":
+            return ["repo_events", "ci_runs"];
+        case "feishu":
+            return ["message_events"];
+        case "local_event":
+            return ["events"];
+        case "remote_source":
+            return ["default"];
+    }
+}
+function getHostConfigFields(hostType) {
+    switch (hostType) {
+        case "github":
+            return [
+                { name: "uxcAuth", type: "string", description: "Optional shared GitHub auth/runtime profile.", required: false },
+            ];
+        case "feishu":
+            return [
+                { name: "appId", type: "string", description: "Feishu app ID.", required: true },
+                { name: "appSecret", type: "string", description: "Feishu app secret.", required: true },
+                { name: "uxcAuth", type: "string", description: "Optional shared Feishu auth/runtime profile.", required: false },
+            ];
+        case "local_event":
+            return [];
+        case "remote_source":
+            return [];
+    }
+}
+function sourceTypeForStreamRegistration(hostType, streamKind) {
+    if (hostType === "github") {
+        if (streamKind === "ci_runs") {
+            return "github_repo_ci";
+        }
+        return "github_repo";
+    }
+    if (hostType === "feishu") {
+        return "feishu_bot";
+    }
+    if (hostType === "local_event") {
+        return "local_event";
+    }
+    return "remote_source";
+}