@parall/agent-core 1.32.1 → 1.34.0

package/dist/gateway-base.d.ts

@@ -106,6 +106,8 @@ export declare class ParallAgentGateway {
     private handleScheduleFire;
     private fetchAndHandleApprovalDecided;
     private catchUpFromDispatch;
+    private buildOfflineSummary;
+    private formatAge;
     private handleHello;
     private waitForDrain;
     private shutdown;

package/dist/gateway-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"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"}

package/dist/gateway-base.js

@@ -1610,8 +1610,29 @@ export class ParallAgentGateway {
         return dispatched;
     }
     async catchUpFromDispatch() {
+        const OVERFLOW_THRESHOLD = 500;
+        const EXPIRE_AGE_HOURS = 24;
+        const CATCHUP_MAX = 10;
+        let expireSummary = null;
+        let overflowMode = false;
+        try {
+            const { count } = await this.opts.client.getDispatchPendingCount(this.opts.config.org_id);
+            if (count > OVERFLOW_THRESHOLD) {
+                overflowMode = true;
+                const result = await this.opts.client.expireDispatch(this.opts.config.org_id, EXPIRE_AGE_HOURS);
+                if (result.total > 0) {
+                    this.opts.log?.warn(`dispatch catch-up overflow: ${count} pending, expired ${result.total} events older than ${EXPIRE_AGE_HOURS}h`);
+                    expireSummary = this.buildOfflineSummary(result.groups);
+                }
+            }
+        }
+        catch (err) {
+            this.opts.log?.warn(`dispatch catch-up overflow check failed: ${String(err)}`);
+        }
         let cursor;
         let processed = 0;
+        let skipped = 0;
+        const skippedByType = new Map();
         do {
             const page = await this.opts.client.getDispatch(this.opts.config.org_id, {
                 limit: 50,
@@ -1622,6 +1643,18 @@ export class ParallAgentGateway {
                 // will only reject. Items remain unacked for the replacement pod.
                 if (this.shuttingDown)
                     break;
+                if (overflowMode && processed >= CATCHUP_MAX) {
+                    try {
+                        await this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id);
+                        skipped++;
+                        const key = item.event_type;
+                        skippedByType.set(key, (skippedByType.get(key) ?? 0) + 1);
+                    }
+                    catch {
+                        this.opts.log?.warn(`catch-up skip ack failed for ${item.id}, leaving pending`);
+                    }
+                    continue;
+                }
                 processed++;
                 try {
                     let dispatched = false;
@@ -1706,10 +1739,54 @@ export class ParallAgentGateway {
             // and the next page would be wasted API work the replacement pod redoes.
             cursor = !this.shuttingDown && page.has_more ? page.next_cursor : undefined;
         } while (cursor);
-        if (processed > 0) {
-            this.opts.log?.info(`dispatch catch-up: processed ${processed}`);
+        if (expireSummary || skipped > 0) {
+            const parts = [];
+            if (expireSummary)
+                parts.push(expireSummary);
+            if (skipped > 0) {
+                const recentLines = [...skippedByType.entries()]
+                    .map(([type, count]) => `- ${count} recent ${type.replace('.', ' ').replace('_', ' ')} events`)
+                    .join('\n');
+                parts.push(expireSummary
+                    ? `Additionally, ${skipped} recent events exceeded the catch-up limit and were skipped:\n${recentLines}`
+                    : `[Offline Summary] You were offline. ${skipped} pending events exceeded the catch-up limit and were skipped:\n${recentLines}\n\nUse your tools (read messages, check tasks) to review anything still relevant.`);
+            }
+            const fullSummary = parts.join('\n\n');
+            this.pendingRestartNotification = this.pendingRestartNotification
+                ? `${this.pendingRestartNotification}\n\n${fullSummary}`
+                : fullSummary;
+        }
+        if (processed > 0 || skipped > 0) {
+            this.opts.log?.info(`dispatch catch-up: processed ${processed}, skipped ${skipped}`);
         }
     }
+    buildOfflineSummary(groups) {
+        const lines = [
+            '[Offline Summary] You were offline and had a large backlog of pending events. The following old events were skipped:',
+        ];
+        for (const g of groups) {
+            const age = this.formatAge(g.oldest);
+            if (g.chat_id && g.event_type === 'message') {
+                const name = g.chat_name ?? g.chat_id;
+                lines.push(`- ${g.count} messages in "${name}" (oldest: ${age})`);
+            }
+            else {
+                const label = g.event_type.replace('.', ' ').replace('_', ' ');
+                lines.push(`- ${g.count} ${label} events (oldest: ${age})`);
+            }
+        }
+        lines.push('');
+        lines.push('These events were too old to process individually. Use your tools (read messages, check tasks) to review anything still relevant.');
+        return lines.join('\n');
+    }
+    formatAge(iso) {
+        const ms = Date.now() - new Date(iso).getTime();
+        const hours = Math.floor(ms / 3_600_000);
+        if (hours < 24)
+            return `${hours}h ago`;
+        const days = Math.floor(hours / 24);
+        return `${days}d ago`;
+    }
     async handleHello(data) {
         const { client, config, log } = this.opts;
         this.sessionId = data.session_id ?? '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.32.1",
+  "version": "1.34.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.32.1"
+    "@parall/sdk": "1.34.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/gateway-base.ts

@@ -1979,8 +1979,34 @@ export class ParallAgentGateway {
   }
 
   private async catchUpFromDispatch() {
+    const OVERFLOW_THRESHOLD = 500;
+    const EXPIRE_AGE_HOURS = 24;
+    const CATCHUP_MAX = 10;
+    let expireSummary: string | null = null;
+    let overflowMode = false;
+
+    try {
+      const { count } = await this.opts.client.getDispatchPendingCount(this.opts.config.org_id);
+      if (count > OVERFLOW_THRESHOLD) {
+        overflowMode = true;
+        const result = await this.opts.client.expireDispatch(
+          this.opts.config.org_id,
+          EXPIRE_AGE_HOURS,
+        );
+        if (result.total > 0) {
+          this.opts.log?.warn(
+            `dispatch catch-up overflow: ${count} pending, expired ${result.total} events older than ${EXPIRE_AGE_HOURS}h`,
+          );
+          expireSummary = this.buildOfflineSummary(result.groups);
+        }
+      }
+    } catch (err) {
+      this.opts.log?.warn(`dispatch catch-up overflow check failed: ${String(err)}`);
+    }
     let cursor: string | undefined;
     let processed = 0;
+    let skipped = 0;
+    const skippedByType = new Map<string, number>();
 
     do {
       const page = await this.opts.client.getDispatch(this.opts.config.org_id, {
@@ -1993,6 +2019,18 @@ export class ParallAgentGateway {
         // will only reject. Items remain unacked for the replacement pod.
         if (this.shuttingDown) break;
 
+        if (overflowMode && processed >= CATCHUP_MAX) {
+          try {
+            await this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id);
+            skipped++;
+            const key = item.event_type;
+            skippedByType.set(key, (skippedByType.get(key) ?? 0) + 1);
+          } catch {
+            this.opts.log?.warn(`catch-up skip ack failed for ${item.id}, leaving pending`);
+          }
+          continue;
+        }
+
         processed++;
         try {
           let dispatched = false;
@@ -2096,9 +2134,69 @@ export class ParallAgentGateway {
       cursor = !this.shuttingDown && page.has_more ? page.next_cursor : undefined;
     } while (cursor);
 
-    if (processed > 0) {
-      this.opts.log?.info(`dispatch catch-up: processed ${processed}`);
+    if (expireSummary || skipped > 0) {
+      const parts: string[] = [];
+      if (expireSummary) parts.push(expireSummary);
+      if (skipped > 0) {
+        const recentLines = [...skippedByType.entries()]
+          .map(
+            ([type, count]) =>
+              `- ${count} recent ${type.replace('.', ' ').replace('_', ' ')} events`,
+          )
+          .join('\n');
+        parts.push(
+          expireSummary
+            ? `Additionally, ${skipped} recent events exceeded the catch-up limit and were skipped:\n${recentLines}`
+            : `[Offline Summary] You were offline. ${skipped} pending events exceeded the catch-up limit and were skipped:\n${recentLines}\n\nUse your tools (read messages, check tasks) to review anything still relevant.`,
+        );
+      }
+      const fullSummary = parts.join('\n\n');
+      this.pendingRestartNotification = this.pendingRestartNotification
+        ? `${this.pendingRestartNotification}\n\n${fullSummary}`
+        : fullSummary;
     }
+
+    if (processed > 0 || skipped > 0) {
+      this.opts.log?.info(`dispatch catch-up: processed ${processed}, skipped ${skipped}`);
+    }
+  }
+
+  private buildOfflineSummary(
+    groups: Array<{
+      chat_id: string | null;
+      chat_name?: string | null;
+      event_type: string;
+      count: number;
+      oldest: string;
+      newest: string;
+    }>,
+  ): string {
+    const lines: string[] = [
+      '[Offline Summary] You were offline and had a large backlog of pending events. The following old events were skipped:',
+    ];
+    for (const g of groups) {
+      const age = this.formatAge(g.oldest);
+      if (g.chat_id && g.event_type === 'message') {
+        const name = g.chat_name ?? g.chat_id;
+        lines.push(`- ${g.count} messages in "${name}" (oldest: ${age})`);
+      } else {
+        const label = g.event_type.replace('.', ' ').replace('_', ' ');
+        lines.push(`- ${g.count} ${label} events (oldest: ${age})`);
+      }
+    }
+    lines.push('');
+    lines.push(
+      'These events were too old to process individually. Use your tools (read messages, check tasks) to review anything still relevant.',
+    );
+    return lines.join('\n');
+  }
+
+  private formatAge(iso: string): string {
+    const ms = Date.now() - new Date(iso).getTime();
+    const hours = Math.floor(ms / 3_600_000);
+    if (hours < 24) return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
   }
 
   private async handleHello(data: HelloData) {