@animalabs/agent-framework 0.15.0 → 0.16.0

package/src/gate/event-gate.ts

@@ -532,6 +532,10 @@ export class EventGate {
   // Inference buffering
   private inferring = new Set<string>();
   private inferenceBuffer: PendingEvent[] = [];
+  /** Host quiesce suppression — see setQuiesced. */
+  private quiesced = false;
+  /** Lifetime count of buffer-cap evictions (see bufferForInference). */
+  private droppedBufferedEvents = 0;
 
   // Per-policy stats
   private stats = new Map<string, PolicyStats>();
@@ -1470,8 +1474,11 @@ export class EventGate {
     const events = state.events;
     this.debounceTimers.delete(policyName);
 
-    // If any agent is currently inferring, buffer for later (with cap)
-    if (this.inferring.size > 0) {
+    // If any agent is currently inferring — or the host is quiesced — buffer
+    // for later (with cap). While quiesced, delivering would write a
+    // "[Gate: N events]" message into the very context being operated on
+    // mid-surgery; buffering composes them and they land at resume.
+    if (this.inferring.size > 0 || this.quiesced) {
       this.bufferForInference(events);
       return;
     }
@@ -1563,8 +1570,26 @@ export class EventGate {
 
   onInferenceEnded(agentName: string): void {
     this.inferring.delete(agentName);
+    this.flushInferenceBufferIfClear();
+  }
 
-    // Flush inference buffer if no agents are inferring
+  /**
+   * Host quiesce suppression (issue #122). While set, debounce firings buffer
+   * instead of writing gate messages into context; clearing it flushes the
+   * buffer through the same path a turn's end uses. Self-wake and sleep-expiry
+   * timers deliberately do NOT route through this — their inference requests
+   * are per-agent targeted pushes that the framework's quiesce wake gate parks
+   * and releases at resume, whereas the buffer's deliverEvents broadcasts a
+   * wake to every agent.
+   */
+  setQuiesced(quiesced: boolean): void {
+    if (this.quiesced === quiesced) return;
+    this.quiesced = quiesced;
+    if (!quiesced) this.flushInferenceBufferIfClear();
+  }
+
+  private flushInferenceBufferIfClear(): void {
+    if (this.quiesced) return;
     if (this.inferring.size === 0 && this.inferenceBuffer.length > 0) {
       const events = this.inferenceBuffer.splice(0);
       // Defer to avoid re-entrancy inside trace callbacks
@@ -1576,10 +1601,16 @@ export class EventGate {
    *  A non-empty `inferring` with a stale timestamp + growing `bufferedEvents`
    *  is the signature of the wake-wedge: an agent stuck mid-"inference" so all
    *  incoming events buffer and never trigger. */
-  inferenceDiagnostics(): { inferring: string[]; bufferedEvents: number; sleepUntil: number } {
+  inferenceDiagnostics(): {
+    inferring: string[];
+    bufferedEvents: number;
+    droppedBufferedEvents: number;
+    sleepUntil: number;
+  } {
     return {
       inferring: [...this.inferring],
       bufferedEvents: this.inferenceBuffer.length,
+      droppedBufferedEvents: this.droppedBufferedEvents,
       sleepUntil: this.sleepUntil,
     };
   }
@@ -1593,6 +1624,18 @@ export class EventGate {
     for (const event of events) {
       if (this.inferenceBuffer.length >= MAX_INFERENCE_BUFFER) {
         this.inferenceBuffer.shift(); // Drop oldest
+        // Telemetry (issue #122): quiesce stretches buffering from
+        // single-inference minutes to operator-length windows, so silent
+        // eviction is no longer a corner case — count and log it, or the
+        // resume flush reads as complete when it isn't.
+        this.droppedBufferedEvents++;
+        if (this.droppedBufferedEvents % 50 === 1) {
+          console.error(
+            `[gate] inference buffer cap (${MAX_INFERENCE_BUFFER}) — dropped ` +
+            `${this.droppedBufferedEvents} oldest buffered event(s)` +
+            `${this.quiesced ? ' during quiesce' : ''}; the flush on release will be incomplete`,
+          );
+        }
       }
       this.inferenceBuffer.push(event);
     }

package/src/index.ts

@@ -2,7 +2,8 @@
 export * from './types/index.js';
 
 // Core classes
-export { AgentFramework } from './framework.js';
+export { AgentFramework, BudgetPreflightError, ResumeBlockedError } from './framework.js';
+export type { RuntimeSettingsPreview, HostModeStatus } from './framework.js';
 export { Agent } from './agent.js';
 export type { StartStreamResult } from './agent.js';
 export { ProcessQueueImpl } from './queue.js';
@@ -124,6 +125,9 @@ export type {
   DiscordAwarenessRef,
   DiscordSuppressionInterval,
 } from './recovery/discord-awareness-outbox.js';
+// Live operator surgery (rollback / suppress) and its durable action log
+export { OperatorLog, OperatorActionError, defaultOperatorLogPath } from './operator-log.js';
+export type { OperatorLogEntry, OperatorLogInput, OperatorRequester } from './operator-log.js';
 export { createOfflineRecoveryBranch } from './recovery/offline-branch.js';
 export type {
   OfflineRecoveryBranchOptions,