bosun 0.39.2 → 0.40.0

package/.env.example

@@ -348,6 +348,10 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # INTERNAL_EXECUTOR_BASE_BRANCH_PARALLEL=0
 # How often to poll kanban for new tasks in ms (default: 30000)
 # INTERNAL_EXECUTOR_POLL_MS=30000
+# Fail-fast policy for workflow start guards when a task appears missing in task-store.
+# false (default): allow dispatch and emit start_guard_bypass audit event
+# true: block dispatch and emit start_guard_blocked audit event
+# BOSUN_STRICT_START_GUARD_MISSING_TASK=false
 # SDK to use: "auto" | "codex" | "copilot" | "claude" | "gemini" | "opencode" (default: auto)
 # INTERNAL_EXECUTOR_SDK=auto
 # Timeout per task execution in ms (default: 5400000 = 90 min)

package/README.md

@@ -5,12 +5,18 @@
 
 Bosun is a production-grade control plane for an autonomous software engineer. It plans and routes work across executors, automates PR lifecycles, and keeps operators in control through Telegram, the Mini App dashboard, and optional WhatsApp notifications.
 
+## Why "Bosun"?
+
+_The name "Bosun" comes from "boatswain", the ship's officer responsible for coordinating deck work, keeping operations moving, and translating command into disciplined execution._
+
+_That maps directly to the Bosun project: it does not replace the captain or crew, it orchestrates the work. Our Bosun plans tasks, routes them to the right executors, enforces operational checks, and keeps humans in control while the system keeps delivery moving. Autonomous engineering with you in control of the operation._
+
 <p align="center">
   <a href="https://bosun.engineer">Website</a> · <a href="https://bosun.engineer/docs/">Docs</a> · <a href="https://github.com/virtengine/bosun?tab=readme-ov-file#bosun">GitHub</a> · <a href="https://www.npmjs.com/package/bosun">npm</a> · <a href="https://github.com/virtengine/bosun/issues">Issues</a>
 </p>
 
 <p align="center">
-  <img src="site/social-card.png" alt="bosun — AI agent supervisor" width="100%" />
+  <img src="site/workflows.png" alt="Bosun Workflows for Autonomous Engineering" width="100%" />
 </p>
 
 <p align="center">
@@ -105,18 +111,10 @@ Setup profiles for default workflow behavior:
 | Codex (OpenAI)    | `codex-sdk`          | `OPENAI_API_KEY`                                                                      |
 | Copilot (VS Code) | `copilot-sdk`        | VS Code session                                                                       |
 | Claude            | `claude-sdk`         | `ANTHROPIC_API_KEY`                                                                   |
-| OpenCode          | `opencode-sdk`       | `OPENCODE_MODEL` (e.g. `anthropic/claude-opus-4-5`), `OPENCODE_PORT` (default `4096`) |
+| OpenCode          | `opencode-sdk`       | `OPENCODE_MODEL` (e.g. `anthropic/claude-opus-4-6`), `OPENCODE_PORT` (default `4096`) |
 
 Set `primaryAgent` in `.bosun/bosun.config.json` or choose an executor preset during `bosun --setup`.
 
----
-
-## Telegram weekly report
-
-- Run `/weekly` to generate the operator weekly agent-work report on demand.
-- Use `/report weekly` as an alias.
-- Optional scheduler knobs in `.env`: `TELEGRAM_WEEKLY_REPORT_ENABLED`, `TELEGRAM_WEEKLY_REPORT_DAY`, `TELEGRAM_WEEKLY_REPORT_HOUR` (UTC), and `TELEGRAM_WEEKLY_REPORT_DAYS`.
-
 ## Daemon and sentinel startup
 
 - `bosun --daemon` starts the long-running daemon/monitor.
@@ -130,19 +128,15 @@ Set `primaryAgent` in `.bosun/bosun.config.json` or choose an executor preset du
 
 **Source docs (markdown):** `_docs/` is the source of truth for long-form documentation. The website should be generated from the same markdown content so docs stay in sync.
 
-Key references:
+**Product docs and implementation notes:** `docs/` contains focused guides, design notes, and operator-facing references that are kept alongside the codebase.
 
-- [GitHub adapter enhancements](_docs/KANBAN_GITHUB_ENHANCEMENT.md)
-- [GitHub Projects v2 index](_docs/GITHUB_PROJECTS_V2_INDEX.md)
-- [GitHub Projects v2 quickstart](_docs/GITHUB_PROJECTS_V2_QUICKSTART.md)
-- [GitHub Projects v2 API](_docs/GITHUB_PROJECTS_V2_API.md)
-- [GitHub Projects v2 monitoring](_docs/GITHUB_PROJECTS_V2_MONITORING.md)
-- [GitHub Projects v2 checklist](_docs/GITHUB_PROJECTS_V2_IMPLEMENTATION_CHECKLIST.md)
-- [Jira integration](_docs/JIRA_INTEGRATION.md)
-- [Workflows](_docs/WORKFLOWS.md)
-- [Agent logging quickstart](docs/agent-logging-quickstart.md)
-- [Agent logging design](docs/agent-work-logging-design.md)
-- [Agent logging summary](docs/AGENT_LOGGING_SUMMARY.md)
+Key places to start:
+
+- `README.md` - install, setup, and operational overview
+- `_docs/WORKFLOWS.md` - workflow system and built-in templates
+- `docs/workflows-and-libraries.md` - workflow composition and library behavior
+- `docs/agent-logging-quickstart.md` - agent work logging quickstart
+- `docs/agent-work-logging-design.md` - logging design and event model
 
 ---
 
@@ -152,7 +146,7 @@ Bosun enforces a strict quality pipeline in both local hooks and CI:
 
 - **Pre-commit hooks** auto-format and lint staged files.
 - **Pre-push hooks** run targeted checks based on changed files (Go, portal, docs).
-- **Demo load smoke test** runs in `npm test` and blocks push if `site/indexv2.html` or `site/ui/demo.html` fails to load required assets.
+- **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.
 
 Local commands you can run any time:
@@ -172,18 +166,23 @@ npm run hooks:install
 
 ## Repository layout
 
-- `cli.mjs` — entrypoint for the supervisor
-- `monitor.mjs` — main orchestration loop
-- `config.mjs` — unified config loader
-- `ui-server.mjs` — Telegram Mini App backend
-- `site/` — marketing + docs website
-- `docs/` and `_docs/` — documentation sources (markdown)
+- `cli.mjs` — CLI entrypoint for setup, daemon, desktop, and operator commands
+- `setup.mjs` — interactive setup flow and config bootstrap
+- `infra/` — monitor loop, recovery, lifecycle services, and runtime plumbing
+- `workflow/` and `workflow-templates/` — workflow engine, nodes, adapters, and built-in templates
+- `task/` — task execution, claims, archiving, and lifecycle ownership
+- `server/` — setup server, Mini App backend, and API endpoints
+- `ui/` — Mini App frontend assets and operator dashboard modules
+- `telegram/` — Telegram bot, sentinel, and channel integrations
+- `github/` and `kanban/` — GitHub auth/webhooks and Vibe-Kanban adapters
+- `workspace/` — shared workspace registry, context indexing, and worktree lifecycle
+- `shell/` and `agent/` — executor integrations, prompts, hooks, and fleet coordination
+- `site/` — marketing site and generated docs website assets
+- `docs/` and `_docs/` — product docs, deep technical references, and long-form source material
+- `tools/` and `tests/` — build utilities, release checks, and regression coverage
 
 ---
 
 ## License
 
 Apache-2.0
-
-<!-- GitHub Analytics Pixel -->
-<img src="https://cloud.umami.is/p/iR78WZdwe" alt="" width="1" height="1" style="display:none;" />

package/agent/agent-custom-tools.mjs

@@ -677,7 +677,7 @@ export async function promoteToGlobal(rootDir, toolId) {
  * and reflect on whether to create new tools.
  *
  * @param {string} rootDir
- * @param {{ limit?: number, category?: string, tags?: string[], emitReflectHint?: boolean, activeSkills?: string[], agentType?: string, template?: string, includeBuiltins?: boolean }} [opts]
+ * @param {{ limit?: number, category?: string, tags?: string[], emitReflectHint?: boolean, activeSkills?: string[], agentType?: string, template?: string, includeBuiltins?: boolean, eagerOnly?: boolean, discoveryMode?: boolean }} [opts]
  * @returns {string}
  */
 export function getToolsPromptBlock(rootDir, opts = {}) {
@@ -691,6 +691,8 @@ export function getToolsPromptBlock(rootDir, opts = {}) {
     agentType,
     template,
     includeBuiltins = true,
+    eagerOnly = false,
+    discoveryMode = false,
   } = opts;
 
   let tools;
@@ -712,11 +714,25 @@ export function getToolsPromptBlock(rootDir, opts = {}) {
     tools = listCustomTools(rootDir, { category, tags, includeBuiltins }).slice(0, limit);
   }
 
+  if (eagerOnly) {
+    tools = tools.filter((tool) => {
+      if (tool.autoInject) return true;
+      if (activeSkills?.length > 0 && tool.skills?.length > 0) {
+        return activeSkills.some((skill) => tool.skills.includes(skill));
+      }
+      return false;
+    });
+  }
+
   const lines = [
     "## Custom Tools Library",
     "",
-    "The following reusable helper scripts are available. Run them via",
-    "`node <tool>.mjs`, `bash <tool>.sh`, or `python3 <tool>.py`.",
+    discoveryMode
+      ? "Only eagerly-loaded tools are listed below. Use the MCP discovery tools to find the rest at runtime."
+      : "The following reusable helper scripts are available. Run them via",
+    discoveryMode
+      ? "Use `search`, then `get_schema`, then `execute` for tools not listed here. Use `call_discovered_tool` only for simple direct calls."
+      : "`node <tool>.mjs`, `bash <tool>.sh`, or `python3 <tool>.py`.",
     "Built-in tools live in `bosun/tools/`; workspace tools in `.bosun/tools/`.",
     "",
   ];

package/agent/agent-pool.mjs

@@ -2228,16 +2228,25 @@ export async function launchEphemeralThread(
       if (mcpCfg.enabled !== false) {
         const requestedIds = launchExtra.mcpServers || [];
         const defaultIds = mcpCfg.defaultServers || [];
+        const registry = await getMcpRegistry();
+        let resolved = [];
         if (requestedIds.length || defaultIds.length) {
-          const registry = await getMcpRegistry();
-          const resolved = await registry.resolveMcpServersForAgent(
+          resolved = await registry.resolveMcpServersForAgent(
             cwd,
             requestedIds,
             { defaultServers: defaultIds, catalogOverrides: mcpCfg.catalogOverrides || {} },
           );
-          if (resolved.length) {
-            launchExtra._resolvedMcpServers = resolved;
-          }
+        }
+        if (typeof registry.wrapServersWithDiscoveryProxy === "function") {
+          resolved = registry.wrapServersWithDiscoveryProxy(cwd, resolved, {
+            enabled: mcpCfg.useDiscoveryProxy !== false,
+            includeCustomTools: mcpCfg.includeCustomToolsInDiscoveryProxy !== false,
+            cacheTtlMs: mcpCfg.discoveryProxyCacheTtlMs,
+            executeTimeoutMs: mcpCfg.discoveryProxyExecuteTimeoutMs,
+          });
+        }
+        if (resolved.length) {
+          launchExtra._resolvedMcpServers = resolved;
         }
       }
       launchExtra._mcpResolved = true;

package/agent/agent-prompts.mjs

@@ -770,7 +770,7 @@ CLI:
   bosun task delete <id>
   bosun task stats [--json]
   bosun task import <file.json>
-  bosun task plan --count N
+  Planner workflow: POST /api/workflows/launch-template {"templateId":"template-task-planner"} or /plan [count] [focus]
 
 REST API (port 18432):
   GET  /api/tasks[?status=todo]
@@ -868,7 +868,7 @@ to the Bosun workspace, task board, coding agents, and system operations.
 You can do everything Bosun can — through voice. This includes:
 - **Task management**: List, create, update, delete, search, and comment on tasks
 - **Agent delegation**: Send work to coding agents (Codex, Copilot, Claude, Gemini, OpenCode)
-- **Agent steering**: Use /ask (read-only), /agent (code changes), or /plan (architecture)
+- **Agent steering**: Use /ask (read-only), /agent (code changes), or /plan (run task planner workflow)
 - **System monitoring**: Check fleet status, agent health, system configuration
 - **Workspace navigation**: Read files, list directories, search code
 - **Workflow management**: List and inspect workflow templates

package/agent/bosun-skills.mjs

@@ -62,6 +62,7 @@ function emitSkillInvokeEvent(skillName, skillTitle, opts = {}) {
  *   filename  – the .md file written into skills/
  *   title     – short human-readable name
  *   tags      – array of lowercase tags agents use to match skills to tasks
+ *   important – eagerly inline this skill into agent context when matched
  *   scope     – "global" | "bosun" (bosun-specific internals)
  *   content   – the full Markdown skill text
  */
@@ -70,6 +71,7 @@ export const BUILTIN_SKILLS = [
     filename: "background-task-execution.md",
     title: "Background Task Execution",
     tags: ["background", "task", "reliability", "heartbeat", "stall", "completion"],
+    important: true,
     scope: "global",
     content: `# Skill: Background Task Execution
 
@@ -147,6 +149,7 @@ Your worktree path is provided via \`BOSUN_WORKTREE_PATH\`. Stay inside it.
     filename: "pr-workflow.md",
     title: "Pull Request Workflow",
     tags: ["pr", "pull-request", "github", "review", "ci", "merge"],
+    important: true,
     scope: "global",
     content: `# Skill: Pull Request Workflow
 
@@ -209,6 +212,7 @@ gh run list --limit 5  # recent workflow runs
     filename: "error-recovery.md",
     title: "Error Recovery Patterns",
     tags: ["error", "recovery", "retry", "debug", "failure"],
+    important: true,
     scope: "global",
     content: `# Skill: Error Recovery Patterns
 
@@ -1079,6 +1083,35 @@ export function buildSkillsIndex(skillsDir) {
     /* directory may not exist yet */
   }
 
+  function extractSkillFileMetadata(filePath) {
+    let content = "";
+    try {
+      content = readFileSync(filePath, "utf8");
+    } catch {
+      return { title: "", tags: [], important: false };
+    }
+
+    let title = "";
+    let tags = [];
+    let important = false;
+
+    const tagMatch = /<!--\s*tags:\s*(.+?)\s*-->/i.exec(content);
+    if (tagMatch) {
+      tags = tagMatch[1].split(/[,\s]+/).map((t) => t.trim().toLowerCase()).filter(Boolean);
+    }
+
+    const importantMatch = /<!--\s*(?:important|eager)\s*:\s*(true|false|yes|no|on|off|1|0)\s*-->/i.exec(content);
+    if (importantMatch) {
+      const raw = String(importantMatch[1] || "").trim().toLowerCase();
+      important = raw === "true" || raw === "yes" || raw === "on" || raw === "1";
+    }
+
+    const h1 = /^#\s+(?:Skill: )?(.+)/m.exec(content);
+    if (h1) title = h1[1].trim();
+
+    return { title, tags, important };
+  }
+
   for (const filename of files.toSorted((a, b) => a.localeCompare(b))) {
     const filePath = resolve(skillsDir, filename);
     let stat;
@@ -1087,31 +1120,26 @@ export function buildSkillsIndex(skillsDir) {
     const builtin = builtinByFilename[filename];
     let title = basename(filename, ".md").replaceAll("-", " ").replaceAll(/\b\w/g, (c) => c.toUpperCase());
     let tags = [];
+    let important = false;
     let scope = "global";
 
     if (builtin) {
       title = builtin.title;
       tags = builtin.tags;
+      important = builtin.important === true;
       scope = builtin.scope;
     } else {
-      // Try to extract tags from the first `<!--tags: ... -->` comment or a
-      // "## Tags" / "## Tags:" section in the skill file.
-      try {
-        const content = readFileSync(filePath, "utf8");
-        const tagMatch = /<!--\s*tags:\s*(.+?)\s*-->/i.exec(content);
-        if (tagMatch) {
-          tags = tagMatch[1].split(/[,\s]+/).map((t) => t.trim().toLowerCase()).filter(Boolean);
-        } else {
-          const h1 = /^#\s+(?:Skill: )?(.+)/m.exec(content);
-          if (h1) title = h1[1].trim();
-        }
-      } catch { /* ignore read errors */ }
+      const metadata = extractSkillFileMetadata(filePath);
+      if (metadata.title) title = metadata.title;
+      tags = metadata.tags;
+      important = metadata.important;
     }
 
     entries.push({
       filename,
       title,
       tags,
+      important,
       scope,
       updatedAt: stat.mtime.toISOString(),
     });
@@ -1212,12 +1240,12 @@ export function findRelevantSkills(bosunHome, taskTitle, taskDescription = "", o
     .filter(({ tags }) =>
       tags.some((tag) => searchText.includes(tag)),
     )
-    .map(({ filename, title, tags }) => {
+    .map(({ filename, title, tags, important }) => {
       let content = "";
       try {
         content = readFileSync(resolve(skillsDir, filename), "utf8");
       } catch { /* skip unreadable files */ }
-      return { filename, title, tags, content };
+      return { filename, title, tags, important: important === true, content };
     })
     .filter(({ content }) => !!content);
 
@@ -1229,3 +1257,44 @@ export function findRelevantSkills(bosunHome, taskTitle, taskDescription = "", o
 
   return matched;
 }
+
+export function buildRelevantSkillsPromptBlock(bosunHome, taskTitle, taskDescription = "", opts = {}) {
+  const {
+    maxListed = 8,
+    includeMatchedSummary = true,
+  } = opts;
+  const matched = findRelevantSkills(bosunHome, taskTitle, taskDescription, opts);
+  if (!matched.length) return "";
+
+  const importantMatches = matched.filter((skill) => skill.important);
+  const summaryMatches = matched.slice(0, Math.max(1, maxListed));
+  const lines = ["## Skills Context", ""];
+
+  if (importantMatches.length > 0) {
+    lines.push(
+      "These matched skills are marked important, so their contents are loaded directly below.",
+      "",
+    );
+    for (const skill of importantMatches) {
+      lines.push(`### Skill: ${skill.title} (\`${skill.filename}\`)`);
+      lines.push(skill.content.trim());
+      lines.push("");
+    }
+  }
+
+  if (includeMatchedSummary) {
+    lines.push("Matched skill files:");
+    for (const skill of summaryMatches) {
+      const tags = Array.isArray(skill.tags) && skill.tags.length > 0
+        ? ` — tags: ${skill.tags.join(", ")}`
+        : "";
+      const importantLabel = skill.important ? " [important]" : "";
+      lines.push(`- \`${skill.filename}\` — ${skill.title}${importantLabel}${tags}`);
+    }
+    lines.push("");
+    lines.push("Load non-important matched skills on demand if you need their details.");
+    lines.push("");
+  }
+
+  return lines.join("\n").trim();
+}

package/agent/primary-agent.mjs

@@ -158,6 +158,59 @@ function appendAttachmentsToPrompt(message, attachments) {
   return { message: `${message}${lines.join("\n")}`, appended: true };
 }
 
+function summarizeContextCompressionItems(items) {
+  if (!Array.isArray(items) || items.length === 0) return null;
+
+  const counts = {
+    agent: 0,
+    user: 0,
+    tool: 0,
+    other: 0,
+  };
+
+  for (const item of items) {
+    if (!item || typeof item !== "object") continue;
+    const compressedTag = String(item._compressed || "").trim().toLowerCase();
+    const text = String(item.text || item.output || item.aggregated_output || "").toLowerCase();
+    const hasToolPlaceholder =
+      Boolean(item._cachedLogId)
+      || text.includes("full output: bosun --tool-log")
+      || text.includes(" chars compressed");
+
+    if (compressedTag.startsWith("agent_")) {
+      counts.agent += 1;
+      continue;
+    }
+    if (compressedTag === "user_breadcrumb") {
+      counts.user += 1;
+      continue;
+    }
+    if (hasToolPlaceholder) {
+      counts.tool += 1;
+      continue;
+    }
+    if (compressedTag) counts.other += 1;
+  }
+
+  const total = counts.agent + counts.user + counts.tool + counts.other;
+  if (total === 0) return null;
+
+  const detailParts = [];
+  if (counts.agent) detailParts.push(`${counts.agent} agent message${counts.agent === 1 ? "" : "s"}`);
+  if (counts.user) detailParts.push(`${counts.user} user prompt${counts.user === 1 ? "" : "s"}`);
+  if (counts.tool) detailParts.push(`${counts.tool} tool output${counts.tool === 1 ? "" : "s"}`);
+  if (counts.other) detailParts.push(`${counts.other} other item${counts.other === 1 ? "" : "s"}`);
+
+  return {
+    total,
+    counts,
+    detail: detailParts.join(", "),
+    content:
+      `Context summarized for continuation: ${total} older item${total === 1 ? "" : "s"} compressed (${detailParts.join(", ")}). ` +
+      `Session history in this view is unchanged.`,
+  };
+}
+
 function buildPrimaryToolCapabilityContract(options = {}) {
   let rootDir = "";
   try {
@@ -795,6 +848,18 @@ export async function execPrimaryPrompt(userMessage, options = {}) {
       timestamp: new Date().toISOString(),
       _sessionType: sessionType,
     });
+    const compressionSummary = summarizeContextCompressionItems(pooled?.items);
+    if (compressionSummary) {
+      tracker.recordEvent(sessionId, {
+        role: "system",
+        type: "system",
+        content: compressionSummary.content,
+        timestamp: new Date().toISOString(),
+        meta: {
+          contextCompression: compressionSummary,
+        },
+      });
+    }
     return pooled;
   }
 
@@ -872,6 +937,18 @@ export async function execPrimaryPrompt(userMessage, options = {}) {
           timestamp: new Date().toISOString(),
           _sessionType: sessionType,
         });
+        const compressionSummary = summarizeContextCompressionItems(result?.items);
+        if (compressionSummary) {
+          tracker.recordEvent(sessionId, {
+            role: "system",
+            type: "system",
+            content: compressionSummary.content,
+            timestamp: new Date().toISOString(),
+            meta: {
+              contextCompression: compressionSummary,
+            },
+          });
+        }
       }
       return result;
     } catch (err) {

package/bosun.schema.json

@@ -1049,6 +1049,28 @@
           },
           "description": "Environment variable overrides keyed by MCP server ID"
         },
+        "useDiscoveryProxy": {
+          "type": "boolean",
+          "default": true,
+          "description": "Wrap resolved MCP servers behind Bosun's compact search/schema/call discovery proxy to reduce tool-definition prompt overhead."
+        },
+        "includeCustomToolsInDiscoveryProxy": {
+          "type": "boolean",
+          "default": true,
+          "description": "Expose Bosun custom tools through the discovery proxy alongside external MCP servers."
+        },
+        "discoveryProxyCacheTtlMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "default": 60000,
+          "description": "How long Bosun caches wrapped MCP tool catalogs inside the discovery proxy before refreshing them."
+        },
+        "discoveryProxyExecuteTimeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "default": 10000,
+          "description": "Default timeout for the discovery proxy execute tool, which runs short orchestration code against discovered tools."
+        },
         "autoInstallDefaults": {
           "type": "boolean",
           "default": true,