bosun 0.41.0 → 0.41.1

package/.env.example

@@ -393,12 +393,20 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # INTERNAL_EXECUTOR_STREAM_RETRY_BASE_MS=2000
 # Stream retry backoff max delay in ms (default: 32000)
 # INTERNAL_EXECUTOR_STREAM_RETRY_MAX_MS=32000
+# Retry queue: route to review workflow once retry count reaches this threshold (default: 3)
+# INTERNAL_EXECUTOR_RETRY_REVIEW_THRESHOLD=3
+# Retry queue: default delay before next retry attempt in ms (default: 15000)
+# INTERNAL_EXECUTOR_RETRY_DELAY_MS=15000
 # Abort/retry turns that emit no stream events within this budget (default: 120000)
 # INTERNAL_EXECUTOR_STREAM_FIRST_EVENT_TIMEOUT_MS=120000
 # Cap number of completed stream items retained per turn (default: 600)
 # INTERNAL_EXECUTOR_STREAM_MAX_ITEMS_PER_TURN=600
 # Truncate oversized item payload strings to this char budget (default: 12000)
 # INTERNAL_EXECUTOR_STREAM_MAX_ITEM_CHARS=12000
+# Prompt cache anchoring mode:
+#   default = best-effort split between system/user prompt
+#   strict  = fail fast if task-specific data leaks into system prompt
+# BOSUN_CACHE_ANCHOR_MODE=default
 # Project requirements profile used by planner/replenishment prompts
 # Allowed: simple-feature | feature | large-feature | system | multi-system
 # PROJECT_REQUIREMENTS_PROFILE=feature

package/README.md

@@ -149,6 +149,26 @@ Bosun enforces a strict quality pipeline in both local hooks and CI:
 - **Demo load smoke test** runs in `npm test` and blocks push if `site/index.html` or `site/ui/demo.html` fails to load required assets.
 - **Prepublish checks** validate package contents and release readiness.
 
+### Codebase annotation audit
+
+Use `bosun audit` to generate and validate repo-level annotations that help future agents navigate the codebase without extra runtime context:
+
+```bash
+# Coverage report for supported source files
+bosun audit scan
+
+# Add missing file summaries and risky-function warnings
+bosun audit generate
+bosun audit warn
+
+# Rebuild lean manifests and the file responsibility index
+bosun audit manifest
+bosun audit index
+bosun audit trim
+
+# CI-safe conformity gate
+bosun audit --ci
+```
 
 Notes:
 

package/agent/agent-event-bus.mjs

@@ -20,6 +20,12 @@
  *   AGENT_EVENT  — Frozen enum of all event types
  */
 
+import {
+  createRetryQueueState,
+  reduceRetryQueue,
+  snapshotRetryQueue,
+} from "./retry-queue.mjs";
+
 const TAG = "[agent-event-bus]";
 
 // ── Event Types ─────────────────────────────────────────────────────────────
@@ -36,6 +42,7 @@ export const AGENT_EVENT = Object.freeze({
   TASK_FAILED: "agent:task-failed",
   TASK_BLOCKED: "agent:task-blocked",
   TASK_STATUS_CHANGE: "agent:task-status-change",
+  SESSION_ACCUMULATED: "session-accumulated",
 
   // ── Agent self-reports (from agent-endpoint) ──
   AGENT_HEARTBEAT: "agent:heartbeat",
@@ -48,6 +55,7 @@ export const AGENT_EVENT = Object.freeze({
   AUTO_COOLDOWN: "agent:auto-cooldown",
   AUTO_BLOCK: "agent:auto-block",
   AUTO_NEW_SESSION: "agent:auto-new-session",
+  RETRY_QUEUE_UPDATED: "agent:retry-queue-updated",
   EXECUTOR_PAUSED: "agent:executor-paused",
   EXECUTOR_RESUMED: "agent:executor-resumed",
 
@@ -80,6 +88,10 @@ const DEFAULTS = {
   dedupeWindowMs: 500,
   /** Max auto-action retries before blocking */
   maxAutoRetries: 5,
+  /** Retry count threshold before routing to review workflow hook (0 disables) */
+  retryReviewThreshold: 0,
+  /** Default delay before next retry attempt appears due */
+  retryDelayMs: 15_000,
 };
 
 // ── AgentEventBus Class ─────────────────────────────────────────────────────
@@ -112,9 +124,27 @@ export class AgentEventBus {
       options.staleThresholdMs || DEFAULTS.staleThresholdMs;
     this._staleCheckIntervalMs =
       options.staleCheckIntervalMs || DEFAULTS.staleCheckIntervalMs;
-    this._maxAutoRetries =
-      options.maxAutoRetries ?? DEFAULTS.maxAutoRetries;
+    this._maxAutoRetries =
+      options.maxAutoRetries ?? DEFAULTS.maxAutoRetries;
     this._dedupeWindowMs = options.dedupeWindowMs || DEFAULTS.dedupeWindowMs;
+    this._retryReviewThreshold =
+      Number.isFinite(Number(options.retryReviewThreshold))
+        ? Math.max(0, Math.trunc(Number(options.retryReviewThreshold)))
+        : DEFAULTS.retryReviewThreshold;
+    this._retryDelayMs =
+      Number.isFinite(Number(options.retryDelayMs))
+        ? Math.max(0, Math.trunc(Number(options.retryDelayMs)))
+        : DEFAULTS.retryDelayMs;
+    this._onRetryThresholdExceeded =
+      typeof options.onRetryThresholdExceeded === "function"
+        ? options.onRetryThresholdExceeded
+        : null;
+    this._setRetryQueueData =
+      typeof options.setRetryQueueData === "function"
+        ? options.setRetryQueueData
+        : (typeof globalThis.__bosun_setRetryQueueData === "function"
+            ? globalThis.__bosun_setRetryQueueData
+            : null);
 
     /** @type {Array<{type: string, taskId: string, payload: object, ts: number}>} ring buffer */
     this._eventLog = [];
@@ -133,6 +163,7 @@ export class AgentEventBus {
 
     /** @type {Map<string, number>} dedup key → last emit timestamp */
     this._recentEmits = new Map();
+    this._retryQueueState = createRetryQueueState();
 
     /** @type {ReturnType<typeof setInterval>|null} */
     this._staleCheckTimer = null;
@@ -257,8 +288,25 @@ export class AgentEventBus {
         retryCount: 0,
         lastRetryAt: 0,
         cooldownUntil: 0,
+        taskTitle: String(task?.title || "").trim(),
       });
+    } else {
+      const state = this._autoActionState.get(taskId);
+      if (state) {
+        if (state.cooldownUntil > 0) {
+          state.cooldownUntil = 0;
+        }
+        const startedTitle = String(task?.title || "").trim();
+        if (startedTitle) {
+          state.taskTitle = startedTitle;
+        }
+        this._autoActionState.set(taskId, state);
+      }
     }
+    this._updateRetryQueue(
+      { type: "remove", taskId },
+      { reason: "task-started", taskId },
+    );
   }
 
   /**
@@ -278,6 +326,10 @@ export class AgentEventBus {
       prNumber: result?.prNumber || null,
     });
     this._autoActionState.delete(taskId);
+    this._updateRetryQueue(
+      { type: "remove", taskId },
+      { reason: "task-completed", taskId },
+    );
 
     // Auto-review
     if (result?.success && this._reviewAgent) {
@@ -300,6 +352,17 @@ export class AgentEventBus {
       error: errorMsg,
     });
 
+    const failedTitle = String(task?.title || "").trim();
+    if (failedTitle) {
+      const state = this._autoActionState.get(taskId) || {
+        retryCount: 0,
+        lastRetryAt: 0,
+        cooldownUntil: 0,
+      };
+      state.taskTitle = failedTitle;
+      this._autoActionState.set(taskId, state);
+    }
+
     if (this._errorDetector) {
       const cls = this._errorDetector.classify(errorMsg, "");
       this._handleClassification(taskId, cls, errorMsg);
@@ -390,6 +453,12 @@ export class AgentEventBus {
         this._sendTelegram(`:close: Task blocked: "${title}" (source: ${source})`);
       }
     }
+    if (newStatus !== "error") {
+      this._updateRetryQueue(
+        { type: "remove", taskId },
+        { reason: `status:${newStatus}`, taskId },
+      );
+    }
   }
 
   /**
@@ -509,6 +578,7 @@ export class AgentEventBus {
    * @returns {object}
    */
   getStatus() {
+    const retryQueue = snapshotRetryQueue(this._retryQueueState);
     return {
       started: this._started,
       eventLogSize: this._eventLog.length,
@@ -516,11 +586,30 @@ export class AgentEventBus {
       errorTrackedTasks: this._errorHistory.size,
       autoActionTasks: this._autoActionState.size,
       listenerCount: this._listeners.size,
+      retryQueue,
       liveness: this.getAgentLiveness(),
       errorPatterns: this.getErrorPatternSummary(),
     };
   }
 
+  getRetryQueue() {
+    return snapshotRetryQueue(this._retryQueueState);
+  }
+
+  clearRetryQueueTask(taskId, reason = "manual") {
+    const id = String(taskId || "").trim();
+    if (!id) return;
+    const state = this._autoActionState.get(id);
+    if (state && state.cooldownUntil > 0) {
+      state.cooldownUntil = 0;
+      this._autoActionState.set(id, state);
+    }
+    this._updateRetryQueue(
+      { type: "remove", taskId: id },
+      { reason, taskId: id },
+    );
+  }
+
   // ══════════════════════════════════════════════════════════════════════════
   //  INTERNAL
   // ══════════════════════════════════════════════════════════════════════════
@@ -538,6 +627,39 @@ export class AgentEventBus {
     }
   }
 
+  _updateRetryQueue(action, meta = {}) {
+    this._retryQueueState = reduceRetryQueue(this._retryQueueState, action);
+    const snapshot = snapshotRetryQueue(this._retryQueueState);
+    if (!this._setRetryQueueData && typeof globalThis.__bosun_setRetryQueueData === "function") {
+      this._setRetryQueueData = globalThis.__bosun_setRetryQueueData;
+    }
+    if (typeof this._setRetryQueueData === "function") {
+      try {
+        this._setRetryQueueData(snapshot);
+      } catch {
+        /* best effort */
+      }
+    }
+    this.emit(AGENT_EVENT.RETRY_QUEUE_UPDATED, meta.taskId || "system", {
+      reason: meta.reason || "retry-queue-updated",
+      retryQueue: snapshot,
+    });
+  }
+
+  _tryTriggerRetryThresholdReview(payload) {
+    if (!this._onRetryThresholdExceeded) return;
+    try {
+      const maybePromise = this._onRetryThresholdExceeded(payload);
+      if (maybePromise && typeof maybePromise.then === "function") {
+        maybePromise.catch((err) => {
+          console.warn(`${TAG} retry-threshold hook failed:`, err?.message || err);
+        });
+      }
+    } catch (err) {
+      console.warn(`${TAG} retry-threshold hook failed:`, err?.message || err);
+    }
+  }
+
   _handleClassification(taskId, classification, rawError) {
     const ts = Date.now();
     if (!this._errorHistory.has(taskId)) {
@@ -597,6 +719,10 @@ export class AgentEventBus {
       cooldownUntil: 0,
     };
     const now = Date.now();
+    const task = this._resolveTask(taskId);
+    const taskTitle =
+      String(task?.title || "").trim()
+      || String(this._autoActionState.get(taskId)?.taskTitle || "").trim();
 
     if (state.cooldownUntil > now) {
       console.log(
@@ -607,6 +733,33 @@ export class AgentEventBus {
 
     switch (action) {
       case "retry_with_prompt": {
+        if (this._retryReviewThreshold > 0 && state.retryCount >= this._retryReviewThreshold) {
+          const reason =
+            recovery?.reason ||
+            `retry threshold reached (${state.retryCount}/${this._retryReviewThreshold})`;
+          this._updateRetryQueue(
+            { type: "mark-exhausted", taskId },
+            { reason: "retry-threshold-exceeded", taskId },
+          );
+          this.emit(AGENT_EVENT.AUTO_REVIEW, taskId, {
+            reason,
+            retryCount: state.retryCount,
+            threshold: this._retryReviewThreshold,
+            pattern: classification?.pattern || null,
+            source: "retry-threshold",
+          });
+          this._tryTriggerRetryThresholdReview({
+            taskId,
+            reason,
+            retryCount: state.retryCount,
+            threshold: this._retryReviewThreshold,
+            classification,
+            recovery,
+            rawError,
+          });
+          console.log(`${TAG} ${taskId} reached retry threshold (${state.retryCount}); routed to review workflow`);
+          return;
+        }
         if (state.retryCount >= this._maxAutoRetries) {
           console.log(`${TAG} ${taskId} exhausted retries (${state.retryCount})`);
           this._executeAutoAction(taskId, "block", recovery, classification, rawError);
@@ -615,6 +768,29 @@ export class AgentEventBus {
         state.retryCount++;
         state.lastRetryAt = now;
         this._autoActionState.set(taskId, state);
+        const retryDelayMs =
+          Number.isFinite(Number(recovery?.cooldownMs))
+            ? Math.max(0, Math.trunc(Number(recovery.cooldownMs)))
+            : this._retryDelayMs;
+        const nextAttemptAt = now + retryDelayMs;
+        this._updateRetryQueue(
+          {
+            type: "bump-count",
+            taskId,
+            retryCount: state.retryCount,
+            item: {
+              taskId,
+              taskTitle,
+              retryCount: state.retryCount,
+              maxRetries: this._maxAutoRetries,
+              reason: recovery?.reason || "error detected",
+              lastError: rawError || recovery?.reason || "",
+              nextAttemptAt,
+              status: "scheduled",
+            },
+          },
+          { reason: "auto-retry", taskId },
+        );
 
         this.emit(AGENT_EVENT.AUTO_RETRY, taskId, {
           retryCount: state.retryCount,
@@ -622,6 +798,8 @@ export class AgentEventBus {
           reason: recovery?.reason || "error detected",
           prompt: recovery?.prompt || null,
           pattern: classification?.pattern,
+          nextAttemptAt,
+          retryDelayMs,
         });
         console.log(
           `${TAG} auto-retry #${state.retryCount}/${this._maxAutoRetries} for ${taskId} (${classification?.pattern || "?"})`,
@@ -640,6 +818,22 @@ export class AgentEventBus {
           reason: recovery?.reason || "rate limited",
           pattern: classification?.pattern,
         });
+        this._updateRetryQueue(
+          {
+            type: "upsert",
+            item: {
+              taskId,
+              taskTitle,
+              retryCount: state.retryCount,
+              maxRetries: this._maxAutoRetries,
+              reason: recovery?.reason || "rate limited",
+              lastError: rawError || recovery?.reason || "",
+              nextAttemptAt: state.cooldownUntil,
+              status: "cooldown",
+            },
+          },
+          { reason: "auto-cooldown", taskId },
+        );
         console.log(
           `${TAG} cooldown ${cooldownMs}ms for ${taskId} (${classification?.pattern || "?"})`,
         );
@@ -647,6 +841,10 @@ export class AgentEventBus {
       }
 
       case "block": {
+        this._updateRetryQueue(
+          { type: "mark-exhausted", taskId },
+          { reason: "auto-block", taskId },
+        );
         this.emit(AGENT_EVENT.AUTO_BLOCK, taskId, {
           reason: recovery?.reason || "too many errors",
           errorCount: recovery?.errorCount || 0,
@@ -659,8 +857,7 @@ export class AgentEventBus {
           } catch { /* best-effort */ }
         }
         if (this._sendTelegram) {
-          const task = this._resolveTask(taskId);
-          const title = task?.title || taskId;
+          const title = taskTitle || taskId;
           this._sendTelegram(
             `:close: Auto-blocked: "${title}" — ${recovery?.reason || "too many errors"}`,
           );
@@ -675,6 +872,24 @@ export class AgentEventBus {
         state.retryCount++;
         state.lastRetryAt = now;
         this._autoActionState.set(taskId, state);
+        this._updateRetryQueue(
+          {
+            type: "bump-count",
+            taskId,
+            retryCount: state.retryCount,
+            item: {
+              taskId,
+              taskTitle,
+              retryCount: state.retryCount,
+              maxRetries: this._maxAutoRetries,
+              reason: recovery?.reason || "new session",
+              lastError: rawError || recovery?.reason || "",
+              nextAttemptAt: now + this._retryDelayMs,
+              status: "new-session",
+            },
+          },
+          { reason: "auto-new-session", taskId },
+        );
 
         this.emit(AGENT_EVENT.AUTO_NEW_SESSION, taskId, {
           reason: recovery?.reason || "session expired / token overflow",
@@ -703,12 +918,15 @@ export class AgentEventBus {
 
       case "manual":
       default: {
+        this._updateRetryQueue(
+          { type: "remove", taskId },
+          { reason: "manual-review", taskId },
+        );
         console.log(
           `${TAG} manual review needed for ${taskId}: ${recovery?.reason || rawError}`,
         );
         if (this._sendTelegram && (recovery?.errorCount || 0) >= 3) {
-          const task = this._resolveTask(taskId);
-          const title = task?.title || taskId;
+          const title = taskTitle || taskId;
           this._sendTelegram(
             `:alert: "${title}" needs manual review: ${recovery?.reason || "repeated errors"}`,
           );
@@ -763,6 +981,29 @@ export class AgentEventBus {
 
   _checkStaleAgents() {
     const now = Date.now();
+    const beforeSnapshot = snapshotRetryQueue(this._retryQueueState);
+    this._retryQueueState = reduceRetryQueue(this._retryQueueState, {
+      type: "expire",
+      now,
+    });
+    const afterSnapshot = snapshotRetryQueue(this._retryQueueState);
+    const queueChanged =
+      beforeSnapshot.count !== afterSnapshot.count ||
+      JSON.stringify(beforeSnapshot.items) !== JSON.stringify(afterSnapshot.items) ||
+      JSON.stringify(beforeSnapshot.stats) !== JSON.stringify(afterSnapshot.stats);
+    if (queueChanged && typeof this._setRetryQueueData === "function") {
+      try {
+        this._setRetryQueueData(afterSnapshot);
+      } catch {
+        /* best effort */
+      }
+    }
+    if (queueChanged) {
+      this.emit(AGENT_EVENT.RETRY_QUEUE_UPDATED, "system", {
+        reason: "expire",
+        retryQueue: afterSnapshot,
+      });
+    }
     for (const [taskId, lastHb] of this._heartbeats) {
       const elapsed = now - lastHb;
       if (elapsed >= this._staleThresholdMs) {
@@ -821,3 +1062,4 @@ export class AgentEventBus {
 export function createAgentEventBus(options) {
   return new AgentEventBus(options);
 }
+