@integrity-labs/agt-cli 0.27.115 → 0.27.117

package/dist/lib/manager-worker.js

@@ -17,7 +17,7 @@ import {
   provisionStopHook,
   requireHost,
   safeWriteJsonAtomic
-} from "../chunk-EOMWSV4B.js";
+} from "../chunk-SDRBYSRO.js";
 import {
   getProjectDir as getProjectDir2,
   getReadyTasks,
@@ -971,6 +971,99 @@ function formatStatusMessage(events, windowMs) {
   return `Circuit breaker tripped: ${events.length} restarts in ${windowLabel} (${breakdown}); most recent=${last.reason} at ${new Date(last.at).toISOString()}`;
 }
 
+// src/lib/mcp-flap-dampener.ts
+var DEFAULT_WINDOW_MS2 = 6e5;
+var DEFAULT_MIN_TRANSITIONS = 4;
+var DEFAULT_MIN_DISTINCT = 2;
+function readEnvNumber2(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function membershipSignature(keys) {
+  return [...new Set(keys)].sort().join(",");
+}
+var McpFlapDampener = class {
+  windowMs;
+  minTransitions;
+  minDistinct;
+  now;
+  history = /* @__PURE__ */ new Map();
+  flapping = /* @__PURE__ */ new Set();
+  constructor(opts = {}) {
+    this.windowMs = opts.windowMs ?? readEnvNumber2("AGT_MCP_FLAP_WINDOW_MS", DEFAULT_WINDOW_MS2);
+    this.minTransitions = opts.minTransitions ?? readEnvNumber2("AGT_MCP_FLAP_MIN_TRANSITIONS", DEFAULT_MIN_TRANSITIONS);
+    this.minDistinct = opts.minDistinct ?? readEnvNumber2("AGT_MCP_FLAP_MIN_DISTINCT", DEFAULT_MIN_DISTINCT);
+    this.now = opts.now ?? Date.now;
+    if (!Number.isFinite(this.windowMs) || this.windowMs < 1e3) {
+      throw new Error("mcp-flap-dampener windowMs must be a finite number >= 1000");
+    }
+    if (!Number.isFinite(this.minTransitions) || this.minTransitions < 2) {
+      throw new Error("mcp-flap-dampener minTransitions must be a finite number >= 2");
+    }
+    if (!Number.isFinite(this.minDistinct) || this.minDistinct < 2) {
+      throw new Error("mcp-flap-dampener minDistinct must be a finite number >= 2");
+    }
+  }
+  key(codeName, channel) {
+    return `${codeName}\0${channel}`;
+  }
+  /**
+   * Record an observed membership signature for (codeName, channel) and return
+   * the current flap decision. Call this on every poll where the manager has
+   * computed the desired set — including unchanged polls — so a set that has
+   * gone quiet ages out of the window and the channel recovers.
+   */
+  record(codeName, channel, signature) {
+    const k = this.key(codeName, channel);
+    const at = this.now();
+    const cutoff = at - this.windowMs;
+    const prior = (this.history.get(k) ?? []).filter((o) => o.at >= cutoff);
+    prior.push({ sig: signature, at });
+    this.history.set(k, prior);
+    let transitions = 0;
+    for (let i = 1; i < prior.length; i++) {
+      if (prior[i].sig !== prior[i - 1].sig) transitions++;
+    }
+    const distinctStates = new Set(prior.map((o) => o.sig)).size;
+    const revisited = prior.slice(0, -1).some((o, i) => o.sig === signature && i !== prior.length - 2);
+    const transitionNow = prior.length >= 2 && prior[prior.length - 1].sig !== prior[prior.length - 2].sig;
+    const oscillating = transitions >= this.minTransitions && distinctStates >= this.minDistinct && revisited;
+    const wasFlapping = this.flapping.has(k);
+    let onset = false;
+    if (wasFlapping) {
+      if (!transitionNow) this.flapping.delete(k);
+    } else if (transitionNow && oscillating) {
+      this.flapping.add(k);
+      onset = true;
+    }
+    return {
+      flapping: this.flapping.has(k),
+      distinctStates,
+      transitions,
+      windowCount: prior.length,
+      onset
+    };
+  }
+  /** True if (codeName, channel) is currently dampened. */
+  isFlapping(codeName, channel) {
+    return this.flapping.has(this.key(codeName, channel));
+  }
+  /** Drop all state for an agent (called on deprovision / agent removal). */
+  forget(codeName) {
+    const prefix = `${codeName}\0`;
+    for (const k of [...this.history.keys()]) {
+      if (k.startsWith(prefix)) this.history.delete(k);
+    }
+    for (const k of [...this.flapping]) {
+      if (k.startsWith(prefix)) this.flapping.delete(k);
+    }
+  }
+};
+var FLAP_CHANNEL_INTEGRATIONS = "integrations";
+var FLAP_CHANNEL_MANAGED_MCP = "managed-mcp";
+
 // src/lib/auto-resume.ts
 var DEFAULT_QUIET_MS = 18e5;
 var DEFAULT_BACKOFF_RESET_MS = 864e5;
@@ -3803,6 +3896,19 @@ function hasRevokedResiduals(state6) {
 var pendingSessionRestarts = /* @__PURE__ */ new Map();
 var restartBreaker = new RestartBreaker();
 var reportedTrips = /* @__PURE__ */ new Map();
+var mcpFlapDampener = new McpFlapDampener();
+function recordConfigChurnEvent(agentId, codeName, channel, signature) {
+  api.post("/host/mcp-config-churn", {
+    agent_id: agentId,
+    code_name: codeName,
+    channel,
+    signature
+  }).catch((err) => {
+    log(
+      `[mcp-flap-dampener] failed to record config-churn event for '${codeName}' (${channel}) (ENG-6123): ${err.message} \u2014 local suppression still active; CloudWatch metric will under-count`
+    );
+  });
+}
 function recordRestartForBreaker(codeName, reason) {
   const result = restartBreaker.record(codeName, reason);
   if (!result.tripped || !result.trip) return;
@@ -3901,12 +4007,17 @@ function scheduleSessionRestart(codeName, delayMs, reason, breakerReason = "hot-
     pendingSessionRestarts.delete(codeName);
     const gate = restartGateFor(codeName, breakerReason);
     if (gate !== "bypass" && gate !== "proceed") {
-      log(
-        `[maintenance-window] Deferring '${reason}' restart for '${codeName}' (${gate}) \u2014 re-checking in ${RESTART_DEFER_RECHECK_MS / 1e3}s`
-      );
+      const lastLogged = deferLogThrottle.get(codeName);
+      if (lastLogged === void 0 || Date.now() - lastLogged >= DEFER_LOG_THROTTLE_MS) {
+        log(
+          `[maintenance-window] Deferring '${reason}' restart for '${codeName}' (${gate}) \u2014 re-checking every ${RESTART_DEFER_RECHECK_MS / 1e3}s until the window opens`
+        );
+        deferLogThrottle.set(codeName, Date.now());
+      }
       scheduleSessionRestart(codeName, RESTART_DEFER_RECHECK_MS, reason, breakerReason);
       return;
     }
+    deferLogThrottle.delete(codeName);
     stopPersistentSession(codeName, log);
     runningMcpHashes.delete(codeName);
     recordRestartForBreaker(codeName, breakerReason);
@@ -3920,9 +4031,12 @@ function cancelPendingSessionRestart(codeName) {
   if (!existing) return;
   clearTimeout(existing);
   pendingSessionRestarts.delete(codeName);
+  deferLogThrottle.delete(codeName);
   log(`[hot-reload] Cancelled pending restart timer for '${codeName}' (another teardown path is handling it)`);
 }
 var RESTART_DEFER_RECHECK_MS = 6e4;
+var DEFER_LOG_THROTTLE_MS = 6e5;
+var deferLogThrottle = /* @__PURE__ */ new Map();
 var lastInboundMs = /* @__PURE__ */ new Map();
 var consecutiveWedgeCycles = /* @__PURE__ */ new Map();
 function noteInbound(codeName) {
@@ -4099,6 +4213,7 @@ function checkMcpConfigDriftAndScheduleRestart(codeName, projectDir) {
         const removed = decision.addedOrRemoved.filter((k) => !currentKeys.has(k));
         quarantineOnlyDrift = added.length === 0 && removed.length > 0 && removed.every((k) => quarantined.has(k));
       }
+      const flapSuppressed = decision.restart && !quarantineOnlyDrift && mcpFlapDampener.isFlapping(codeName, FLAP_CHANNEL_MANAGED_MCP);
       if (decision.membershipUnknown) {
         clearPresenceReaperState(codeName);
         log(
@@ -4108,6 +4223,10 @@ function checkMcpConfigDriftAndScheduleRestart(codeName, projectDir) {
         log(
           `[channel-quarantine] .mcp.json drift for '${codeName}' is quarantined-channel removal only [${decision.addedOrRemoved.join(", ")}] \u2014 adopting new baseline WITHOUT restart (0-restart-on-removal, ENG-5932)`
         );
+      } else if (flapSuppressed) {
+        log(
+          `[mcp-flap-dampener] .mcp.json membership drift for '${codeName}' [${decision.addedOrRemoved.join(", ")}] held \u2014 managed-MCP set is flapping, adopting baseline WITHOUT restart until it settles (ENG-6123)`
+        );
       } else if (decision.restart) {
         clearPresenceReaperStateForKeys(codeName, new Set(decision.addedOrRemoved));
         log(
@@ -4118,10 +4237,11 @@ function checkMcpConfigDriftAndScheduleRestart(codeName, projectDir) {
           `[hot-reload] .mcp.json value-only drift for '${codeName}' \u2014 preserving presence-reaper state and NOT restarting (ENG-5285/ENG-5537)`
         );
       }
-      if (decision.restart && !quarantineOnlyDrift) {
+      if (decision.restart && !quarantineOnlyDrift && !flapSuppressed) {
         scheduleSessionRestart(codeName, 0, ".mcp.json content change (ENG-4897)");
         runningMcpHashes.delete(codeName);
         runningMcpServerKeys.delete(codeName);
+      } else if (flapSuppressed) {
       } else {
         runningMcpHashes.set(codeName, action.current);
         if (currentKeys) runningMcpServerKeys.set(codeName, currentKeys);
@@ -4216,6 +4336,8 @@ function clearAgentCaches(agentId, codeName) {
   for (const key of taskDisplayInfo.keys()) {
     if (key.startsWith(`${codeName}:`)) taskDisplayInfo.delete(key);
   }
+  mcpFlapDampener.forget(codeName);
+  deferLogThrottle.delete(codeName);
   if (channelCacheMutated) saveChannelHashCache2();
 }
 var cachedFrameworkVersion = null;
@@ -4223,7 +4345,7 @@ var cachedMaintenanceWindow = null;
 var lastVersionCheckAt = 0;
 var VERSION_CHECK_INTERVAL_MS = 5 * 60 * 1e3;
 var lastResponsivenessProbeAt = 0;
-var agtCliVersion = true ? "0.27.115" : "dev";
+var agtCliVersion = true ? "0.27.117" : "dev";
 function resolveBrewPath(execFileSync4) {
   try {
     const out = execFileSync4("which", ["brew"], { timeout: 5e3 }).toString().trim();
@@ -6441,6 +6563,7 @@ async function processAgent(agent, agentStates) {
             const telegramPeers = channelId === "telegram" ? extractCharterTelegramPeers(refreshData.charter?.raw_content ?? "", gateContext) : void 0;
             const slackPeers = channelId === "slack" ? extractCharterSlackPeers(refreshData.charter?.raw_content ?? "", gateContext) : void 0;
             const senderPolicyForCall = channelId === "slack" || channelId === "msteams" ? refreshData.sender_policy ?? void 0 : void 0;
+            const agentAvatarUrl = channelId === "slack" ? (refreshData.agent.avatar_url ?? void 0) || void 0 : void 0;
             frameworkAdapter.writeChannelCredentials(
               agent.code_name,
               channelId,
@@ -6453,7 +6576,8 @@ async function processAgent(agent, agentStates) {
                 telegramPeers,
                 slackPeers,
                 agentTimezone,
-                senderPolicy: senderPolicyForCall
+                senderPolicy: senderPolicyForCall,
+                agentAvatarUrl
               }
             );
             agentState.knownChannelConfigHashes.set(cacheKey, configHash);
@@ -6760,6 +6884,14 @@ async function processAgent(agent, agentStates) {
     if (integrations.length > 0) {
       const intHash = computeIntegrationsHash(integrations);
       const prevIntHash = agentState.knownIntegrationHashes.get(agent.agent_id);
+      const intMembership = membershipSignature(integrations.map((i) => i.definition_id));
+      const intFlap = mcpFlapDampener.record(agent.code_name, FLAP_CHANNEL_INTEGRATIONS, intMembership);
+      if (intFlap.onset) {
+        log(
+          `[mcp-flap-dampener] integration set for '${agent.code_name}' is FLAPPING (${intFlap.transitions} transitions / ${intFlap.distinctStates} states in window) \u2014 suppressing integration-update notices until it settles (ENG-6123)`
+        );
+        recordConfigChurnEvent(agent.agent_id, agent.code_name, FLAP_CHANNEL_INTEGRATIONS, intMembership);
+      }
       if (intHash !== prevIntHash) {
         const projectDir = join8(homedir4(), ".augmented", agent.code_name, "project");
         const envIntPath = join8(projectDir, ".env.integrations");
@@ -6793,11 +6925,15 @@ async function processAgent(agent, agentStates) {
             }
             const names = integrations.map((i) => i.display_name || i.definition_id).join(", ");
             const reapNote = affectedServerKeys.length > 0 ? ` The MCP servers that depend on rotating credentials (${affectedServerKeys.join(", ")}) have been signalled to reconnect.` : "";
-            injectMessage(agent.code_name, "system", `Your integrations have been refreshed. You have access to: ${names}.${reapNote}`, {
-              task_name: "integration-update"
-            }, log).catch(() => {
-            });
-            log(`[hot-reload] Notified '${agent.code_name}' about integration update: ${names} (reaped ${affectedServerKeys.length} stale MCP server(s))`);
+            if (intFlap.flapping) {
+              log(`[mcp-flap-dampener] suppressed integration-update notice for '${agent.code_name}' (set flapping, ENG-6123): ${names}`);
+            } else {
+              injectMessage(agent.code_name, "system", `Your integrations have been refreshed. You have access to: ${names}.${reapNote}`, {
+                task_name: "integration-update"
+              }, log).catch(() => {
+              });
+              log(`[hot-reload] Notified '${agent.code_name}' about integration update: ${names} (reaped ${affectedServerKeys.length} stale MCP server(s))`);
+            }
           } catch (err) {
             rotationHandled = false;
             log(`[hot-reload] Failed to compute / reap affected MCP servers for '${agent.code_name}': ${err.message} \u2014 will retry next tick`);
@@ -6837,6 +6973,14 @@ async function processAgent(agent, agentStates) {
         const prevMcpHash = agentState.knownManagedMcpHashes.get(agent.agent_id);
         const structureHash = managedMcpStructureHash(desiredEntries);
         const prevStructureHash = agentState.knownManagedMcpStructure.get(agent.agent_id);
+        const mcpMembership = membershipSignature(expectedServerIds);
+        const mcpFlap = mcpFlapDampener.record(agent.code_name, FLAP_CHANNEL_MANAGED_MCP, mcpMembership);
+        if (mcpFlap.onset) {
+          log(
+            `[mcp-flap-dampener] managed-MCP set for '${agent.code_name}' is FLAPPING (${mcpFlap.transitions} transitions / ${mcpFlap.distinctStates} states in window) \u2014 suppressing mcp-update notice + restart until it settles (ENG-6123)`
+          );
+          recordConfigChurnEvent(agent.agent_id, agent.code_name, FLAP_CHANNEL_MANAGED_MCP, mcpMembership);
+        }
         if (mcpHash !== prevMcpHash) {
           for (const e of desiredEntries) {
             frameworkAdapter.writeMcpServer(agent.code_name, e.serverId, { url: e.url, headers: e.headers });
@@ -6875,7 +7019,12 @@ async function processAgent(agent, agentStates) {
           }
           agentState.knownManagedMcpHashes.set(agent.agent_id, mcpHash);
           agentState.knownManagedMcpStructure.set(agent.agent_id, structureHash);
-          if (prevStructureHash !== void 0 && structureHash !== prevStructureHash && fwForMcp === "claude-code" && isSessionHealthy(agent.code_name)) {
+          if (prevStructureHash !== void 0 && structureHash !== prevStructureHash && fwForMcp === "claude-code" && isSessionHealthy(agent.code_name) && // ENG-6123: hold the restart + inject-notice while the managed-MCP
+          // membership is oscillating. The .mcp.json above was still written
+          // (the file converges to the live set); we only withhold the
+          // opus-facing notice + the session reload — the two per-flip burns.
+          // When the set settles, the next structural change restarts once.
+          !mcpFlap.flapping) {
             const mcpNames = agentToolkits.map((tk) => tk.toolkit_name).join(", ") || "none (all removed)";
             log(`[hot-reload] MCP servers changed for '${agent.code_name}': ${mcpNames} \u2014 restarting session`);
             const restartNotice = agentToolkits.length > 0 ? `New MCP tool servers have been configured: ${mcpNames}. Note: MCP servers require a session restart to connect. Your manager will restart your session shortly.` : "Managed MCP tool servers were removed. Your manager will restart your session shortly so the session drops those tools.";