@holon-run/agentinbox 1.8.1 → 1.9.0

package/dist/src/adapters.js

@@ -213,6 +213,12 @@ class AdapterRegistry {
         }
         return this.remoteSource.summarizeDigestThread(source, items, grouping);
     }
+    async shouldFlushDigestThread(source, items, context) {
+        if (source.sourceType === "local_event") {
+            return null;
+        }
+        return this.remoteSource.shouldFlushDigestThread(source, items, context);
+    }
     async listDeliveryOperations(source, handle) {
         const module = await this.resolveDeliveryModule(source, handle);
         if (!module?.listDeliveryOperations) {

package/dist/src/service.js

@@ -30,6 +30,7 @@ const DEFAULT_IDLE_SOURCE_GRACE_MS = 30 * 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 DEFAULT_DIGEST_THREAD_RECHECK_MS = 30_000;
 const DIRECT_INBOX_SOURCE_ID = "__agentinbox_direct_text__";
 const DIRECT_INBOX_EVENT_VARIANT = "agentinbox.direct_text_message";
 const TIMER_INBOX_SOURCE_ID = "__agentinbox_timer__";
@@ -1339,7 +1340,10 @@ class AgentInboxService {
             this.store.closeDigestThread(thread.threadId, now);
             thread = null;
         }
-        const flushAfterAt = new Date(Date.now() + (policy.windowMs ?? DEFAULT_INBOX_AGGREGATION_WINDOW_MS)).toISOString();
+        const groupingFlushDelayMs = grouping.flushDelayMs != null && grouping.flushDelayMs >= 0
+            ? grouping.flushDelayMs
+            : null;
+        const flushAfterAt = new Date(Date.now() + (groupingFlushDelayMs ?? policy.windowMs ?? DEFAULT_INBOX_AGGREGATION_WINDOW_MS)).toISOString();
         if (!thread) {
             thread = this.store.createDigestThread({
                 inboxId: input.inbox.inboxId,
@@ -1621,7 +1625,7 @@ class AgentInboxService {
                         source,
                         subscriptionId: subscription.subscriptionId,
                         item,
-                        summary: summarizeSourceEvent(source.sourceType, source.sourceKey, event.eventVariant),
+                        summary: summarizeSourceEvent(source.sourceType, source.sourceKey, event.eventVariant, event.metadata),
                     });
                     insertedEntries.push(...entries);
                     for (const entry of entries) {
@@ -1953,6 +1957,7 @@ class AgentInboxService {
         const inbox = {
             inboxId: (0, util_1.generateCanonicalId)("inb"),
             ownerAgentId: agentId,
+            aggregationEnabled: true,
             createdAt: (0, util_1.nowIso)(),
         };
         this.store.insertInbox(inbox);
@@ -3199,6 +3204,21 @@ class AgentInboxService {
                     this.store.closeDigestThread(thread.threadId, now);
                     continue;
                 }
+                const pendingItems = this.store.listUnackedInboxItemsForDigestThread(thread.threadId);
+                if (pendingItems.length > 0) {
+                    const decision = await this.adapters.shouldFlushDigestThread(source, pendingItems.map((item) => activationItemFromInboxItem(item)), {
+                        threadCreatedAt: thread.createdAt,
+                        lastItemAt: thread.lastItemAt,
+                        now,
+                    });
+                    if (decision && !decision.flush) {
+                        const recheckAfterMs = decision.recheckAfterMs != null && decision.recheckAfterMs > 0
+                            ? decision.recheckAfterMs
+                            : DEFAULT_DIGEST_THREAD_RECHECK_MS;
+                        this.store.updateDigestThreadFlushAfterAt(thread.threadId, new Date(Date.parse(now) + recheckAfterMs).toISOString());
+                        continue;
+                    }
+                }
                 const entry = await this.flushDigestThread(source, thread.threadId);
                 if (!entry) {
                     continue;
@@ -3945,7 +3965,27 @@ function extractHttpStatus(error) {
     }
     return null;
 }
-function summarizeSourceEvent(sourceType, sourceKey, eventVariant) {
+function summarizeSourceEvent(sourceType, sourceKey, eventVariant, metadata = {}) {
+    if (sourceType === "github_repo") {
+        const repo = asNonEmptyString(metadata.repoFullName) ?? sourceKey;
+        const number = typeof metadata.number === "number" && Number.isInteger(metadata.number)
+            ? metadata.number
+            : null;
+        const isPullRequest = metadata.isPullRequest === true;
+        const resource = number == null ? null : `${isPullRequest ? "PR" : "Issue"} #${number}`;
+        const action = asNonEmptyString(metadata.action) ?? eventVariant.split(".")[1] ?? "updated";
+        const title = asNonEmptyString(metadata.title);
+        const author = asNonEmptyString(metadata.author);
+        const url = asNonEmptyString(metadata.url);
+        const details = [
+            resource,
+            action,
+            title ? `"${truncateSummary(title, 160)}"` : null,
+            author ? `by @${author}` : null,
+            url,
+        ].filter((value) => value != null);
+        return `${sourceType}:${repo}${details.length > 0 ? ` ${details.join(" ")}` : `:${eventVariant}`}`;
+    }
     if (sourceType === "github_repo_ci") {
         const parts = eventVariant.split(".");
         const [, second, third, fourth] = parts;
@@ -3967,6 +4007,19 @@ function summarizeSourceEvent(sourceType, sourceKey, eventVariant) {
     }
     return `${sourceType}:${sourceKey}:${eventVariant}`;
 }
+function asNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function truncateSummary(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
 function summarizeDirectInboxMessage(sender) {
     if (sender) {
         return `direct_text_message:${sender}`;

package/dist/src/sources/github_ci.js

@@ -1,12 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GithubCiSourceRuntime = exports.GithubActionsUxcClient = exports.DEFAULT_GITHUB_CI_PER_PAGE = exports.DEFAULT_GITHUB_CI_POLL_INTERVAL_SECS = exports.GITHUB_CI_ENDPOINT = void 0;
+exports.GithubCiSourceRuntime = exports.GithubActionsUxcClient = exports.DEFAULT_GITHUB_CI_DIGEST_FLUSH_TIMEOUT_SECS = exports.DEFAULT_GITHUB_CI_DIGEST_QUIET_WINDOW_SECS = exports.DEFAULT_GITHUB_CI_PER_PAGE = exports.DEFAULT_GITHUB_CI_POLL_INTERVAL_SECS = exports.GITHUB_CI_ENDPOINT = void 0;
 exports.normalizeGithubWorkflowRunEvent = normalizeGithubWorkflowRunEvent;
 exports.parseGithubCiSourceConfig = parseGithubCiSourceConfig;
+exports.githubCiDigestQuietWindowMs = githubCiDigestQuietWindowMs;
+exports.githubCiDigestFlushTimeoutMs = githubCiDigestFlushTimeoutMs;
+exports.deriveGithubCiNotificationGrouping = deriveGithubCiNotificationGrouping;
+exports.decideGithubCiDigestFlush = decideGithubCiDigestFlush;
+exports.summarizeGithubCiDigestThread = summarizeGithubCiDigestThread;
 const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
 exports.GITHUB_CI_ENDPOINT = "https://api.github.com";
 exports.DEFAULT_GITHUB_CI_POLL_INTERVAL_SECS = 30;
 exports.DEFAULT_GITHUB_CI_PER_PAGE = 20;
+exports.DEFAULT_GITHUB_CI_DIGEST_QUIET_WINDOW_SECS = 120;
+exports.DEFAULT_GITHUB_CI_DIGEST_FLUSH_TIMEOUT_SECS = 60 * 60;
+const GITHUB_CI_DIGEST_RECHECK_MS = 30_000;
+const GITHUB_CI_DIGEST_MIN_RECHECK_MS = 1_000;
 const MAX_PAGES_PER_SYNC = 10;
 const MAX_SEEN_KEYS = 512;
 const MAX_ERROR_BACKOFF_MULTIPLIER = 8;
@@ -335,6 +344,8 @@ function parseGithubCiSourceConfig(source) {
             eventFilter: asString(config.eventFilter) ?? undefined,
             branch: asString(config.branch) ?? undefined,
             statusFilter: asString(config.statusFilter) ?? undefined,
+            digestQuietWindowSecs: asNumber(config.digestQuietWindowSecs) ?? undefined,
+            digestFlushTimeoutSecs: asNumber(config.digestFlushTimeoutSecs) ?? undefined,
         };
     }
     return {
@@ -346,8 +357,207 @@ function parseGithubCiSourceConfig(source) {
         eventFilter: asString(config.eventFilter) ?? undefined,
         branch: asString(config.branch) ?? undefined,
         statusFilter: asString(config.statusFilter) ?? undefined,
+        digestQuietWindowSecs: asNumber(config.digestQuietWindowSecs) ?? undefined,
+        digestFlushTimeoutSecs: asNumber(config.digestFlushTimeoutSecs) ?? undefined,
     };
 }
+function githubCiDigestQuietWindowMs(config) {
+    return Math.max(0, (config.digestQuietWindowSecs ?? exports.DEFAULT_GITHUB_CI_DIGEST_QUIET_WINDOW_SECS) * 1000);
+}
+function githubCiDigestFlushTimeoutMs(config) {
+    return Math.max(0, (config.digestFlushTimeoutSecs ?? exports.DEFAULT_GITHUB_CI_DIGEST_FLUSH_TIMEOUT_SECS) * 1000);
+}
+function firstPullRequestNumber(item) {
+    const numbers = item.metadata.pullRequestNumbers;
+    if (!Array.isArray(numbers)) {
+        return null;
+    }
+    for (const number of numbers) {
+        if (typeof number === "number" && Number.isInteger(number) && number > 0) {
+            return number;
+        }
+    }
+    return null;
+}
+/**
+ * Groups workflow-run notifications at the pull-request level so a push that
+ * fans out into many workflow runs produces one digest thread per PR instead
+ * of one per run. Runs without a PR association fall back to per-push grouping
+ * by head sha.
+ */
+function deriveGithubCiNotificationGrouping(item, config) {
+    const workflowRunId = asNumber(item.metadata.workflowRunId);
+    if (!workflowRunId) {
+        return null;
+    }
+    const repoFullName = asString(item.metadata.repoFullName) ?? `${config.owner}/${config.repo}`;
+    const headSha = asString(item.metadata.headSha);
+    const prNumber = firstPullRequestNumber(item);
+    const resourceRef = prNumber != null
+        ? `pr:${repoFullName}#${prNumber}`
+        : headSha
+            ? `push:${repoFullName}:${headSha}`
+            : null;
+    if (!resourceRef) {
+        return null;
+    }
+    const conclusion = asString(item.metadata.conclusion);
+    const actionableFailure = Boolean(conclusion) && conclusion !== "success" && conclusion !== "skipped";
+    return {
+        groupable: true,
+        resourceRef,
+        eventFamily: "ci_updates",
+        summaryHint: prNumber != null
+            ? `CI updates for ${repoFullName}#${prNumber}`
+            : `CI updates for ${repoFullName}@${shortSha(headSha)}`,
+        flushClass: actionableFailure ? "immediate" : "normal",
+        flushDelayMs: githubCiDigestQuietWindowMs(config),
+    };
+}
+/**
+ * Post-hoc flush decision for a PR-level CI digest thread: flush once every
+ * workflow run observed for the thread's latest head sha has reached a
+ * terminal state (or the hard timeout expires). GitHub exposes no prior about
+ * how many runs a push will create, so readiness is judged from the observed
+ * event stream itself.
+ */
+function decideGithubCiDigestFlush(items, config, context) {
+    if (items.length === 0) {
+        return { flush: true, reason: "no pending items" };
+    }
+    const ordered = orderItemsByOccurredAt(items);
+    const latestSha = latestHeadSha(ordered);
+    if (!latestSha) {
+        return { flush: true, reason: "no head sha" };
+    }
+    const nowMs = Date.parse(context.now);
+    const createdMs = Date.parse(context.threadCreatedAt);
+    const timeoutMs = githubCiDigestFlushTimeoutMs(config);
+    const timedOut = Number.isFinite(nowMs) && Number.isFinite(createdMs) && nowMs - createdMs >= timeoutMs;
+    if (!timedOut) {
+        const runTerminal = new Map();
+        for (const item of ordered) {
+            if (asString(item.metadata.headSha) !== latestSha) {
+                continue;
+            }
+            const runId = asNumber(item.metadata.workflowRunId);
+            if (!runId) {
+                continue;
+            }
+            const status = asString(item.metadata.status);
+            const conclusion = asString(item.metadata.conclusion);
+            // Sticky terminal: out-of-order delivery or timestamp skew must never
+            // downgrade a run that was already observed terminal back to pending,
+            // which would defer the flush until the hard timeout.
+            const observedTerminal = status === "completed" || Boolean(conclusion);
+            runTerminal.set(runId, (runTerminal.get(runId) ?? false) || observedTerminal);
+        }
+        let pending = 0;
+        for (const terminal of runTerminal.values()) {
+            if (!terminal) {
+                pending += 1;
+            }
+        }
+        if (pending > 0) {
+            const remaining = createdMs + timeoutMs - nowMs;
+            const recheckAfterMs = Number.isFinite(remaining)
+                ? Math.min(GITHUB_CI_DIGEST_RECHECK_MS, Math.max(GITHUB_CI_DIGEST_MIN_RECHECK_MS, remaining))
+                : GITHUB_CI_DIGEST_RECHECK_MS;
+            return {
+                flush: false,
+                reason: `${pending} run(s) still pending on ${shortSha(latestSha)}`,
+                recheckAfterMs,
+            };
+        }
+    }
+    return {
+        flush: true,
+        reason: timedOut ? `hard timeout on ${shortSha(latestSha)}` : `all runs terminal on ${shortSha(latestSha)}`,
+    };
+}
+function summarizeGithubCiDigestThread(items) {
+    if (items.length === 0) {
+        return null;
+    }
+    const ordered = orderItemsByOccurredAt(items);
+    let repoFullName = null;
+    let prNumber = null;
+    let latestSha = null;
+    for (const item of ordered) {
+        repoFullName = asString(item.metadata.repoFullName) ?? repoFullName;
+        prNumber = firstPullRequestNumber(item) ?? prNumber;
+        latestSha = asString(item.metadata.headSha) ?? latestSha;
+    }
+    const runs = new Map();
+    for (const item of ordered) {
+        const runId = asNumber(item.metadata.workflowRunId);
+        if (!runId) {
+            continue;
+        }
+        const previous = runs.get(runId) ?? { name: null, conclusion: null };
+        runs.set(runId, {
+            name: asString(item.metadata.name) ?? previous.name,
+            // Sticky conclusion: keep the first observed terminal conclusion so
+            // out-of-order items cannot rewrite a run's reported outcome.
+            conclusion: previous.conclusion ?? asString(item.metadata.conclusion),
+        });
+    }
+    const failed = [];
+    let passed = 0;
+    let running = 0;
+    for (const run of runs.values()) {
+        if (run.conclusion === "success" || run.conclusion === "skipped") {
+            passed += 1;
+        }
+        else if (run.conclusion) {
+            failed.push(run.name ? `${run.name} (${run.conclusion})` : run.conclusion);
+        }
+        else {
+            running += 1;
+        }
+    }
+    const target = repoFullName
+        ? prNumber != null
+            ? `${repoFullName}#${prNumber}`
+            : latestSha
+                ? `${repoFullName}@${shortSha(latestSha)}`
+                : repoFullName
+        : "repository";
+    const parts = [`${runs.size} workflow runs on ${shortSha(latestSha)}`];
+    if (failed.length > 0) {
+        const shown = failed.slice(0, 3).join(", ");
+        parts.push(`${failed.length} failed: ${shown}${failed.length > 3 ? ", …" : ""}`);
+    }
+    if (passed > 0) {
+        parts.push(`${passed} passed`);
+    }
+    if (running > 0) {
+        parts.push(`${running} still running`);
+    }
+    return `CI for ${target}: ${parts.join(", ")}`;
+}
+function orderItemsByOccurredAt(items) {
+    return [...items].sort((left, right) => Date.parse(left.occurredAt) - Date.parse(right.occurredAt));
+}
+function latestHeadSha(orderedItems) {
+    let latestSha = null;
+    let latestAt = Number.NaN;
+    for (const item of orderedItems) {
+        const sha = asString(item.metadata.headSha);
+        if (!sha) {
+            continue;
+        }
+        const at = Date.parse(item.occurredAt);
+        if (latestSha == null || (!Number.isNaN(at) && (Number.isNaN(latestAt) || at >= latestAt))) {
+            latestSha = sha;
+            latestAt = at;
+        }
+    }
+    return latestSha;
+}
+function shortSha(sha) {
+    return sha ? sha.slice(0, 7) : "unknown";
+}
 function parseGithubCiCheckpoint(checkpoint) {
     if (!checkpoint) {
         return {};

package/dist/src/sources/remote.js

@@ -299,6 +299,16 @@ class RemoteSourceRuntime {
         }
         return module.deriveNotificationGrouping(item, moduleInputSource(source));
     }
+    async shouldFlushDigestThread(source, items, context) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return null;
+        }
+        const module = await this.moduleRegistry.resolve(source, this.homeDir);
+        if (typeof module.shouldFlushDigestThread !== "function") {
+            return null;
+        }
+        return module.shouldFlushDigestThread(items, moduleInputSource(source), context);
+    }
     async summarizeDigestThread(source, items, grouping) {
         if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
             return null;

package/dist/src/sources/remote_modules.js

@@ -123,6 +123,7 @@ function validateModuleContract(module, sourcePath) {
     validateOptionalHook(module.projectLifecycleSignal, "projectLifecycleSignal", sourcePath);
     validateOptionalHook(module.deriveInlinePreview, "deriveInlinePreview", sourcePath);
     validateOptionalHook(module.deriveNotificationGrouping, "deriveNotificationGrouping", sourcePath);
+    validateOptionalHook(module.shouldFlushDigestThread, "shouldFlushDigestThread", sourcePath);
     validateOptionalHook(module.listDeliveryOperations, "listDeliveryOperations", sourcePath);
     validateOptionalHook(module.invokeDeliveryOperation, "invokeDeliveryOperation", sourcePath);
     validateOptionalHook(module.listSourceOperations, "listSourceOperations", sourcePath);
@@ -401,26 +402,18 @@ const GITHUB_REPO_CI_MODULE = {
         }
         return parts.join(" ");
     },
-    deriveNotificationGrouping(item) {
-        const workflowRunId = typeof item.metadata.workflowRunId === "number" ? item.metadata.workflowRunId : null;
-        if (!workflowRunId) {
-            return null;
-        }
-        const conclusion = asNonEmptyString(item.metadata.conclusion);
-        const status = asNonEmptyString(item.metadata.status);
-        return {
-            groupable: true,
-            resourceRef: `workflow_run:${workflowRunId}`,
-            eventFamily: "ci_updates",
-            summaryHint: `CI updates for run #${workflowRunId}`,
-            flushClass: conclusion || status === "completed" ? "immediate" : "normal",
-        };
+    deriveNotificationGrouping(item, source) {
+        return (0, github_ci_1.deriveGithubCiNotificationGrouping)(item, (0, github_ci_1.parseGithubCiSourceConfig)(source));
+    },
+    shouldFlushDigestThread(items, source, context) {
+        return (0, github_ci_1.decideGithubCiDigestFlush)(items, (0, github_ci_1.parseGithubCiSourceConfig)(source), context);
     },
     summarizeDigestThread(items, _source, grouping) {
-        if (!grouping.summaryHint || items.length === 0) {
+        if (items.length === 0) {
             return null;
         }
-        return `${items.length} ${grouping.summaryHint}`;
+        return (0, github_ci_1.summarizeGithubCiDigestThread)(items)
+            ?? (grouping.summaryHint ? `${items.length} ${grouping.summaryHint}` : null);
     },
     validateConfig(source) {
         (0, github_ci_1.parseGithubCiSourceConfig)(source);

package/dist/src/store.js

@@ -1710,6 +1710,14 @@ class AgentInboxStore {
         const rows = this.getAll("select * from digest_threads where status = 'open' order by created_at asc, thread_id asc");
         return rows.map((row) => this.mapDigestThread(row));
     }
+    updateDigestThreadFlushAfterAt(threadId, flushAfterAt) {
+        this.run(`
+      update digest_threads
+      set flush_after_at = ?, updated_at = ?
+      where thread_id = ? and status = 'open'
+      `, [flushAfterAt, (0, util_1.nowIso)(), threadId]);
+        this.persist();
+    }
     materializeDigestSnapshot(input) {
         const thread = this.getDigestThread(input.threadId);
         if (!thread) {

package/drizzle/migrations/0009_inbox_aggregation_default_on.sql

@@ -0,0 +1,8 @@
+-- Aggregation is now enabled by default for agent inboxes: bursty events on
+-- the same resource collapse into one digest notification instead of waking
+-- the agent once per event. Existing inboxes were left disabled by the old
+-- default, so flip them on in bulk; explicit opt-outs can set the flag back
+-- to 0 per inbox via the inbox aggregation policy.
+update inboxes
+set aggregation_enabled = 1
+where aggregation_enabled = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {