bosun 0.41.10 → 0.42.1

package/.env.example

@@ -1039,6 +1039,18 @@ COPILOT_CLOUD_DISABLED=true
 # WORKFLOW_AUTOMATION_ENABLED=true
 # Optional dedup window to avoid event storms (milliseconds).
 # WORKFLOW_EVENT_DEDUP_WINDOW_MS=15000
+# Monitor self-healing retry policy for startup unstick operations
+# (stale dispatch polling and workflow-history resume).
+# Max bounded retry attempts before terminal escalation.
+# WORKFLOW_RECOVERY_MAX_ATTEMPTS=5
+# Escalation warning threshold for repeated failures (must be <= max attempts).
+# WORKFLOW_RECOVERY_ESCALATION_THRESHOLD=3
+# Exponential backoff base delay in ms.
+# WORKFLOW_RECOVERY_BACKOFF_BASE_MS=5000
+# Exponential backoff maximum delay in ms.
+# WORKFLOW_RECOVERY_BACKOFF_MAX_MS=60000
+# Random jitter ratio (0.0-0.9) applied to backoff to prevent retry storms.
+# WORKFLOW_RECOVERY_BACKOFF_JITTER_RATIO=0.2
 
 # ─── GitHub Issue Reconciler ─────────────────────────────────────────────────
 # Periodically reconciles open GitHub issues against open/merged PRs.

package/README.md

@@ -144,6 +144,8 @@ Set `primaryAgent` in `.bosun/bosun.config.json` or choose an executor preset du
 - `bosun --daemon --sentinel` starts daemon + sentinel together (recommended for unattended operation).
 - `bosun --terminate` is the clean reset command when you suspect stale/ghost processes.
 
+Telegram operators can pull the weekly agent work summary with `/weekly [days]` or `/report weekly [days]`. To post it automatically once per week, set `TELEGRAM_WEEKLY_REPORT_ENABLED=true` together with `TELEGRAM_WEEKLY_REPORT_DAY`, `TELEGRAM_WEEKLY_REPORT_HOUR`, and optional `TELEGRAM_WEEKLY_REPORT_DAYS`.
+
 ## Documentation
 
 **Published docs (website):** https://bosun.engineer/docs/

package/agent/agent-hooks.mjs

@@ -144,7 +144,7 @@ export const HOOK_EVENTS = Object.freeze([
  * Canonical SDK names.
  * @type {readonly string[]}
  */
-const VALID_SDKS = Object.freeze(["codex", "copilot", "claude", "opencode"]);
+const VALID_SDKS = Object.freeze(["codex", "copilot", "claude", "opencode", "gemini"]);
 
 /**
  * Wildcard indicating a hook applies to all SDKs.
@@ -1198,3 +1198,58 @@ function _truncate(str, maxLen) {
   if (!str || str.length <= maxLen) return str ?? "";
   return str.slice(0, maxLen) + "\n... (truncated)";
 }
+
+// ── Hook Library Integration ────────────────────────────────────────────────
+
+/**
+ * Register hooks from the hook-library into the agent-hooks runtime registry.
+ * This bridges the declarative hook catalog with the execution engine.
+ *
+ * @param {Record<string, Array<{id: string, command: string, description?: string, timeout?: number, blocking?: boolean, sdks?: string[], builtin?: boolean, retryable?: boolean, maxRetries?: number, env?: Record<string,string>}>>} hooksByEvent
+ *   - Output of getHooksForRegistration() from hook-library.mjs
+ * @returns {{ registered: number, skipped: number }}
+ */
+export function registerLibraryHooks(hooksByEvent) {
+  let registered = 0;
+  let skipped = 0;
+
+  if (!hooksByEvent || typeof hooksByEvent !== "object") {
+    return { registered, skipped };
+  }
+
+  for (const [event, hooks] of Object.entries(hooksByEvent)) {
+    if (!HOOK_EVENTS.includes(event)) {
+      console.warn(`${TAG} unknown hook event from library: ${event}`);
+      skipped += hooks.length;
+      continue;
+    }
+
+    for (const hook of hooks) {
+      // Skip if a hook with this ID is already registered (built-in takes priority)
+      const existing = (_registry.get(event) ?? []).find((h) => h.id === hook.id);
+      if (existing) {
+        skipped++;
+        continue;
+      }
+
+      registerHook(event, {
+        id: hook.id,
+        command: hook.command,
+        description: hook.description ?? "",
+        timeout: hook.timeout ?? DEFAULT_TIMEOUT_MS,
+        blocking: hook.blocking ?? false,
+        sdks: hook.sdks ?? [SDK_WILDCARD],
+        builtin: hook.builtin ?? false,
+        retryable: hook.retryable ?? false,
+        maxRetries: hook.maxRetries,
+        env: hook.env,
+      });
+      registered++;
+    }
+  }
+
+  if (registered > 0) {
+    console.log(`${TAG} registered ${registered} hook(s) from hook library`);
+  }
+  return { registered, skipped };
+}

package/agent/agent-pool.mjs

@@ -2871,6 +2871,19 @@ function sdkSupportsPersistentThreads(sdkName) {
 
 /** @type {Map<string, ActiveSession>} */
 const activeSessions = new Map();
+const ACTIVE_SESSION_LISTENERS = new Set();
+
+function notifyActiveSessionListeners(reason = "update", taskKey = null) {
+  if (ACTIVE_SESSION_LISTENERS.size === 0) return;
+  const snapshot = getActiveSessions();
+  for (const listener of ACTIVE_SESSION_LISTENERS) {
+    try {
+      listener(snapshot, { reason, taskKey });
+    } catch {
+      /* best effort */
+    }
+  }
+}
 
 /** Threshold for approaching-exhaustion warning (80% of MAX_THREAD_TURNS). */
 const THREAD_EXHAUSTION_WARNING_THRESHOLD = Math.floor(MAX_THREAD_TURNS * 0.8);
@@ -2892,6 +2905,7 @@ function registerActiveSession(taskKey, sdk, threadId, sendFn) {
     send: sendFn,
     registeredAt: Date.now(),
   });
+  notifyActiveSessionListeners("start", taskKey);
 }
 
 /**
@@ -2900,6 +2914,7 @@ function registerActiveSession(taskKey, sdk, threadId, sendFn) {
  */
 function unregisterActiveSession(taskKey) {
   activeSessions.delete(taskKey);
+  notifyActiveSessionListeners("end", taskKey);
 }
 
 /**
@@ -2949,15 +2964,31 @@ export function hasActiveSession(taskKey) {
  * Get info about which tasks have active (steerable) sessions.
  * @returns {Array<{ taskKey: string, sdk: string, threadId: string|null, age: number }>}
  */
+export function addActiveSessionListener(listener) {
+  if (typeof listener !== "function") return () => {};
+  ACTIVE_SESSION_LISTENERS.add(listener);
+  return () => ACTIVE_SESSION_LISTENERS.delete(listener);
+}
+
 export function getActiveSessions() {
   const now = Date.now();
   const result = [];
   for (const [key, session] of activeSessions) {
+    const record = threadRegistry.get(key) || null;
+    const createdAt = Number(record?.createdAt || session.registeredAt || now);
+    const lastUsedAt = Number(record?.lastUsedAt || now);
     result.push({
+      id: key,
+      taskId: key,
       taskKey: key,
       sdk: session.sdk,
       threadId: session.threadId,
-      age: now - session.registeredAt,
+      type: "task",
+      status: "active",
+      turnCount: Number(record?.turnCount || 0),
+      createdAt: new Date(createdAt).toISOString(),
+      lastActiveAt: new Date(lastUsedAt).toISOString(),
+      age: Math.max(0, now - createdAt),
     });
   }
   return result;
@@ -3973,3 +4004,5 @@ export function getActiveThreads() {
   }
   return result;
 }
+
+

package/agent/agent-work-report.mjs

@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveRepoRoot } from "../config/repo-root.mjs";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -89,6 +90,12 @@ function defaultLogPaths() {
   };
 }
 
+export function getWeeklyReportStatePath(options = {}) {
+  if (options?.statePath) return resolve(String(options.statePath));
+  const repoRoot = resolveRepoRoot();
+  return resolve(repoRoot, ".cache", "agent-work-logs", "weekly-report-state.json");
+}
+
 async function defaultLoadMetrics() {
   const { metricsPath } = defaultLogPaths();
   return await readJsonlFile(metricsPath);
@@ -99,6 +106,44 @@ async function defaultLoadErrors() {
   return await readJsonlFile(errorsPath);
 }
 
+export async function readWeeklyReportScheduleState(options = {}) {
+  const statePath = getWeeklyReportStatePath(options);
+  try {
+    const raw = await readFile(statePath, "utf8");
+    const parsed = JSON.parse(raw);
+    const lastSentAt = String(parsed?.lastSentAt || "").trim();
+    if (!lastSentAt) {
+      return { statePath, lastSentAt: null };
+    }
+    const lastSentMs = Date.parse(lastSentAt);
+    return {
+      statePath,
+      lastSentAt: Number.isFinite(lastSentMs) ? new Date(lastSentMs).toISOString() : null,
+    };
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return { statePath, lastSentAt: null };
+    }
+    return { statePath, lastSentAt: null };
+  }
+}
+
+export async function writeWeeklyReportScheduleState(lastSentAt, options = {}) {
+  const statePath = getWeeklyReportStatePath(options);
+  const normalized = String(lastSentAt || "").trim();
+  const lastSentMs = Date.parse(normalized);
+  const payload = {
+    lastSentAt: Number.isFinite(lastSentMs) ? new Date(lastSentMs).toISOString() : null,
+    updatedAt: new Date().toISOString(),
+  };
+  await mkdir(dirname(statePath), { recursive: true });
+  await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return {
+    statePath,
+    lastSentAt: payload.lastSentAt,
+  };
+}
+
 export function buildWeeklyAgentWorkSummary(options = {}) {
   const now = toSafeDate(options.now);
   const days = toPositiveDays(options.days, DEFAULT_DAYS);
@@ -359,4 +404,45 @@ export function shouldSendWeeklyReport(options = {}) {
     return true;
   }
   return lastSentMs < scheduledThisWeek.getTime();
-}
+}
+
+export async function runWeeklyAgentWorkReportCli(options = {}) {
+  const argv = Array.isArray(options.argv) ? options.argv : process.argv.slice(2);
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const rawDays = String(argv[0] || "").trim();
+  const parsedDays = Number.parseInt(rawDays, 10);
+  const days = Number.isFinite(parsedDays) && parsedDays > 0 ? parsedDays : undefined;
+
+  try {
+    const report = await generateWeeklyAgentWorkReport({
+      ...(days ? { days } : {}),
+      ...(options.now ? { now: options.now } : {}),
+      ...(typeof options.loadMetrics === "function"
+        ? { loadMetrics: options.loadMetrics }
+        : {}),
+      ...(typeof options.loadErrors === "function"
+        ? { loadErrors: options.loadErrors }
+        : {}),
+    });
+    stdout.write(`${report.text}\n`);
+    if (Array.isArray(report.warnings) && report.warnings.length > 0) {
+      stderr.write(`Warnings: ${report.warnings.join(" | ")}\n`);
+    }
+    return 0;
+  } catch (err) {
+    stderr.write(`Failed to generate weekly agent work report: ${err?.message || err}\n`);
+    return 1;
+  }
+}
+
+const isDirectRun =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+
+if (isDirectRun) {
+  const exitCode = await runWeeklyAgentWorkReportCli();
+  if (exitCode !== 0) {
+    process.exitCode = exitCode;
+  }
+}

package/agent/analyze-agent-work-helpers.mjs

@@ -203,8 +203,10 @@ function buildErrorCorrelationEntries(errors, taskProfiles) {
         count: 0,
         task_ids: new Set(),
         by_executor: {},
+        by_model: {},
         by_size: {},
         by_complexity: {},
+        avg_task_duration_ms: 0,
         sample_message: "",
         first_seen_ts: null,
         last_seen_ts: null,
@@ -240,13 +242,23 @@ function buildErrorCorrelationEntries(errors, taskProfiles) {
       extractSizeLabelFromTitle(error.task_title),
     );
     const executor = resolveKnownValue(profile?.executor, error.executor);
+    const model = resolveKnownValue(profile?.model, error.model);
     const complexity = resolveKnownValue(profile?.complexity);
 
     incrementCounter(entry.by_size, sizeLabel);
     incrementCounter(entry.by_executor, executor);
+    incrementCounter(entry.by_model, model);
     incrementCounter(entry.by_complexity, complexity);
   }
 
+  for (const entry of correlations.values()) {
+    const durations = [...entry.task_ids]
+      .map((taskId) => taskProfiles.get(taskId)?.avg_duration_ms || 0)
+      .filter((duration) => duration > 0);
+    entry.avg_task_duration_ms =
+      durations.length > 0 ? average(durations) : 0;
+  }
+
   return correlations;
 }
 
@@ -300,7 +312,9 @@ export function buildErrorCorrelationJsonPayload(summary, { now } = {}) {
       last_seen: entry.last_seen_ts
         ? new Date(entry.last_seen_ts).toISOString()
         : null,
+      avg_task_duration_ms: entry.avg_task_duration_ms || 0,
       by_executor: buildDistribution(entry.by_executor, entry.count),
+      by_model: buildDistribution(entry.by_model, entry.count),
       by_size: buildDistribution(entry.by_size, entry.count),
       by_complexity: buildDistribution(entry.by_complexity, entry.count),
     })),

package/agent/analyze-agent-work.mjs

@@ -21,7 +21,7 @@
 import { readFile, readdir } from "fs/promises";
 import { createReadStream, existsSync } from "fs";
 import { createInterface } from "readline";
-import { resolve, dirname } from "path";
+import { resolve, dirname, isAbsolute } from "path";
 import { fileURLToPath } from "url";
 import {
   buildErrorClusters,
@@ -44,8 +44,16 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const repoRoot = resolve(__dirname, "../..");
 
+function resolveAgentWorkLogDir() {
+  const configured = String(process.env.AGENT_WORK_LOG_DIR || "").trim();
+  if (!configured) {
+    return resolve(repoRoot, ".cache/agent-work-logs");
+  }
+  return isAbsolute(configured) ? configured : resolve(repoRoot, configured);
+}
+
 // ── Log Paths ───────────────────────────────────────────────────────────────
-const LOG_DIR = resolve(repoRoot, ".cache/agent-work-logs");
+const LOG_DIR = resolveAgentWorkLogDir();
 const STREAM_LOG = resolve(LOG_DIR, "agent-work-stream.jsonl");
 const ERRORS_LOG = resolve(LOG_DIR, "agent-errors.jsonl");
 const METRICS_LOG = resolve(LOG_DIR, "agent-metrics.jsonl");
@@ -339,6 +347,14 @@ function formatDistribution(counts, total, limit = 5) {
     .join(", ");
 }
 
+function formatDurationMs(durationMs) {
+  const value = Number(durationMs) || 0;
+  if (value <= 0) return "unknown";
+  if (value < 1000) return `${value.toFixed(0)}ms`;
+  if (value < 60_000) return `${(value / 1000).toFixed(1)}s`;
+  return `${(value / 60_000).toFixed(1)}m`;
+}
+
 function topN(obj, n) {
   return Object.entries(obj)
     .sort((a, b) => b[1] - a[1])
@@ -478,7 +494,7 @@ async function correlateErrors(options) {
   const errors = await loadErrors({ days: windowDays });
 
   if (errors.length === 0) {
-    const message = "No error data found";
+    const message = "No data found for selected window";
     if (useJson) {
       console.log(
         JSON.stringify(
@@ -522,10 +538,14 @@ async function correlateErrors(options) {
     console.log(
       `  Executors: ${formatDistribution(entry.by_executor, entry.count)}`,
     );
+    console.log(`  Models: ${formatDistribution(entry.by_model, entry.count)}`);
     console.log(`  Sizes: ${formatDistribution(entry.by_size, entry.count)}`);
     console.log(
       `  Complexity: ${formatDistribution(entry.by_complexity, entry.count)}`,
     );
+    console.log(
+      `  Avg task duration: ${formatDurationMs(entry.avg_task_duration_ms)}`,
+    );
     if (entry.sample_message) {
       console.log(
         `  Sample: ${entry.sample_message.slice(0, 100)}${entry.sample_message.length > 100 ? "..." : ""}`,