@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/github/index.ts

@@ -5,6 +5,7 @@ export {
   initGitHub,
   isGitHubEnabled,
   isReactionsEnabled,
+  resetGitHub,
   verifyWebhookSignature,
 } from "./app";
 export {

package/src/github/mentions-aliases.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Alias tests for mentions.ts
+ *
+ * BOT_NAMES is computed once at module load time. In bun test, all test files
+ * share the same process, so mentions.test.ts loads the module first (without
+ * aliases). We use _resetBotNamesForTesting() to recompute from current env.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  _resetBotNamesForTesting,
+  BOT_NAMES,
+  detectMention,
+  extractMentionContext,
+  isBotAssignee,
+} from "./mentions";
+
+const originalAliases = process.env.GITHUB_BOT_ALIASES;
+
+beforeAll(() => {
+  process.env.GITHUB_BOT_ALIASES = "alias1,alias2";
+  _resetBotNamesForTesting();
+});
+
+afterAll(() => {
+  if (originalAliases === undefined) {
+    delete process.env.GITHUB_BOT_ALIASES;
+  } else {
+    process.env.GITHUB_BOT_ALIASES = originalAliases;
+  }
+  _resetBotNamesForTesting();
+});
+
+describe("GITHUB_BOT_ALIASES support", () => {
+  test("BOT_NAMES includes primary name and aliases", () => {
+    expect(BOT_NAMES).toContain("agent-swarm-bot");
+    expect(BOT_NAMES).toContain("alias1");
+    expect(BOT_NAMES).toContain("alias2");
+  });
+
+  test("detectMention recognizes alias mentions", () => {
+    expect(detectMention("@alias1 review this")).toBe(true);
+    expect(detectMention("@alias2 please help")).toBe(true);
+    expect(detectMention("Hey @alias1")).toBe(true);
+  });
+
+  test("detectMention is case-insensitive for aliases", () => {
+    expect(detectMention("@ALIAS1 review")).toBe(true);
+    expect(detectMention("@Alias2 help")).toBe(true);
+  });
+
+  test("detectMention still recognizes primary bot name", () => {
+    expect(detectMention("@agent-swarm-bot review")).toBe(true);
+  });
+
+  test("isBotAssignee recognizes aliases", () => {
+    expect(isBotAssignee("alias1")).toBe(true);
+    expect(isBotAssignee("alias2")).toBe(true);
+    expect(isBotAssignee("ALIAS1")).toBe(true);
+  });
+
+  test("isBotAssignee still recognizes primary bot name", () => {
+    expect(isBotAssignee("agent-swarm-bot")).toBe(true);
+  });
+
+  test("isBotAssignee rejects unknown names", () => {
+    expect(isBotAssignee("not-an-alias")).toBe(false);
+  });
+
+  test("extractMentionContext works with aliases", () => {
+    expect(extractMentionContext("@alias1 review this PR")).toBe("review this PR");
+    expect(extractMentionContext("Hey @alias2 help me")).toBe("Hey  help me");
+  });
+});

package/src/github/mentions.test.ts

@@ -19,8 +19,8 @@ describe("detectMention", () => {
   });
 
   test("is case-insensitive", () => {
-    expect(detectMention("@Agent-Swarm-Bot help")).toBe(true);
-    expect(detectMention("@AGENT-SWARM-BOT help")).toBe(true);
+    expect(detectMention(`@${GITHUB_BOT_NAME.toLowerCase()} help`)).toBe(true);
+    expect(detectMention(`@${GITHUB_BOT_NAME.toUpperCase()} help`)).toBe(true);
   });
 
   test("returns false for no mention", () => {
@@ -62,7 +62,7 @@ describe("extractMentionContext", () => {
   });
 
   test("is case-insensitive", () => {
-    expect(extractMentionContext("@AGENT-SWARM-BOT help me")).toBe("help me");
+    expect(extractMentionContext(`@${GITHUB_BOT_NAME.toUpperCase()} help me`)).toBe("help me");
   });
 
   test("returns empty string for null or undefined", () => {

package/src/github/mentions.ts

@@ -1,11 +1,37 @@
 // Bot name for @mentions (can be overridden via env)
 export const GITHUB_BOT_NAME = process.env.GITHUB_BOT_NAME || "agent-swarm-bot";
 
-// Pattern to detect @<bot-name> mentions (case-insensitive)
-const MENTION_PATTERN = new RegExp(`@${GITHUB_BOT_NAME}\\b`, "i");
+// Additional aliases that also trigger the bot (comma-separated env var)
+// Example: GITHUB_BOT_ALIASES=heysidekick,sidekick,review-bot
+function computeBotNames(): string[] {
+  const primary = GITHUB_BOT_NAME.toLowerCase();
+  const aliases = (process.env.GITHUB_BOT_ALIASES || "")
+    .split(",")
+    .map((a) => a.trim().toLowerCase())
+    .filter(Boolean);
+  return [...new Set([primary, ...aliases])];
+}
+
+function computeMentionPattern(names: string[]): RegExp {
+  return new RegExp(
+    `@(${names.map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`,
+    "i",
+  );
+}
+
+export let BOT_NAMES: string[] = computeBotNames();
+
+// Pattern to detect @<any-name> mentions (case-insensitive)
+let MENTION_PATTERN = computeMentionPattern(BOT_NAMES);
+
+/** Recompute BOT_NAMES and MENTION_PATTERN from current env. For testing only. */
+export function _resetBotNamesForTesting(): void {
+  BOT_NAMES = computeBotNames();
+  MENTION_PATTERN = computeMentionPattern(BOT_NAMES);
+}
 
 /**
- * Check if text contains @<bot-name> mention
+ * Check if text contains @<bot-name-or-alias> mention
  */
 export function detectMention(text: string | null | undefined): boolean {
   if (!text) return false;
@@ -13,7 +39,7 @@ export function detectMention(text: string | null | undefined): boolean {
 }
 
 /**
- * Extract context by removing the @<bot-name> mention from text
+ * Extract context by removing the @<bot-name-or-alias> mention from text
  * Returns the remaining text trimmed
  */
 export function extractMentionContext(text: string | null | undefined): string {
@@ -22,9 +48,9 @@ export function extractMentionContext(text: string | null | undefined): string {
 }
 
 /**
- * Check if the assignee matches our bot name (case-insensitive)
+ * Check if the assignee matches our bot name or any alias (case-insensitive)
  */
 export function isBotAssignee(assigneeLogin: string | undefined): boolean {
   if (!assigneeLogin) return false;
-  return assigneeLogin.toLowerCase() === GITHUB_BOT_NAME.toLowerCase();
+  return BOT_NAMES.includes(assigneeLogin.toLowerCase());
 }

package/src/github/templates.ts

@@ -0,0 +1,398 @@
+/**
+ * GitHub event prompt template definitions.
+ *
+ * Each template is registered at module load time via registerTemplate().
+ * Handlers import this module for the side-effect of registration.
+ *
+ * Template text uses {{variable}} syntax. The resolver interpolates variables
+ * and expands {{@template[id]}} references before returning the final text.
+ */
+
+import { registerTemplate } from "../prompts/registry";
+
+// ============================================================================
+// Common building blocks
+// ============================================================================
+
+registerTemplate({
+  eventType: "common.delegation_instruction",
+  header: "",
+  defaultBody:
+    "\u26a0\ufe0f As lead, DELEGATE this task to a worker agent - do not tackle it yourself.",
+  variables: [],
+  category: "common",
+});
+
+registerTemplate({
+  eventType: "common.command_suggestions.github_pr",
+  header: "",
+  defaultBody: "\ud83d\udca1 Suggested: /review-pr or /respond-github",
+  variables: [],
+  category: "common",
+});
+
+registerTemplate({
+  eventType: "common.command_suggestions.github_issue",
+  header: "",
+  defaultBody: "\ud83d\udca1 Suggested: /implement-issue or /respond-github",
+  variables: [],
+  category: "common",
+});
+
+registerTemplate({
+  eventType: "common.command_suggestions.github_comment_pr",
+  header: "",
+  defaultBody: "\ud83d\udca1 Suggested: /respond-github or /review-pr",
+  variables: [],
+  category: "common",
+});
+
+registerTemplate({
+  eventType: "common.command_suggestions.github_comment_issue",
+  header: "",
+  defaultBody: "\ud83d\udca1 Suggested: /respond-github",
+  variables: [],
+  category: "common",
+});
+
+// ============================================================================
+// Pull Request events
+// ============================================================================
+
+registerTemplate({
+  eventType: "github.pull_request.assigned",
+  header: "[GitHub PR #{{pr_number}}] {{pr_title}}",
+  defaultBody: `Assigned to: @{{bot_name}}
+From: {{sender_login}}
+Repo: {{repo_full_name}}
+Branch: {{head_ref}} \u2192 {{base_ref}}
+URL: {{pr_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_pr]}}`,
+  variables: [
+    { name: "pr_number", description: "Pull request number" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "bot_name", description: "GitHub bot username" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "head_ref", description: "Head branch name" },
+    { name: "base_ref", description: "Base branch name" },
+    { name: "pr_url", description: "Pull request HTML URL" },
+    { name: "context", description: "PR body or title as context" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.pull_request.review_requested",
+  header: "[GitHub PR #{{pr_number}}] {{pr_title}}",
+  defaultBody: `Review requested from: @{{bot_name}}
+From: {{sender_login}}
+Repo: {{repo_full_name}}
+Branch: {{head_ref}} \u2192 {{base_ref}}
+URL: {{pr_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_pr]}}`,
+  variables: [
+    { name: "pr_number", description: "Pull request number" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "bot_name", description: "GitHub bot username" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "head_ref", description: "Head branch name" },
+    { name: "base_ref", description: "Base branch name" },
+    { name: "pr_url", description: "Pull request HTML URL" },
+    { name: "context", description: "PR body or title as context" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.pull_request.closed",
+  header: "{{status_emoji}} [GitHub PR #{{pr_number}}] {{status}}{{merged_by}}",
+  defaultBody: `PR: {{pr_title}}
+Repo: {{repo_full_name}}
+URL: {{pr_url}}
+
+---
+Related task: {{related_task_id}}
+\ud83d\udd00 Consider routing to the same agent working on the related task.
+{{follow_up_suggestion}}`,
+  variables: [
+    { name: "status_emoji", description: "Status emoji (merge or close)" },
+    { name: "pr_number", description: "Pull request number" },
+    { name: "status", description: "MERGED or CLOSED" },
+    { name: "merged_by", description: "Merged by info (e.g. ' by user') or empty" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "pr_url", description: "Pull request HTML URL" },
+    { name: "related_task_id", description: "ID of the related existing task" },
+    {
+      name: "follow_up_suggestion",
+      description: "Suggestion text for merged or closed PR",
+    },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.pull_request.synchronize",
+  header: "\ud83d\udd04 [GitHub PR #{{pr_number}}] New commits pushed",
+  defaultBody: `PR: {{pr_title}}
+Repo: {{repo_full_name}}
+Branch: {{head_ref}}
+New HEAD: {{head_sha_short}}
+URL: {{pr_url}}
+
+---
+Related task: {{related_task_id}}
+\ud83d\udd00 Consider routing to the same agent working on the related task.
+\ud83d\udca1 New commits were pushed. CI will re-run - monitor for results.`,
+  variables: [
+    { name: "pr_number", description: "Pull request number" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "head_ref", description: "Head branch name" },
+    { name: "head_sha_short", description: "Short HEAD SHA (7 chars)" },
+    { name: "pr_url", description: "Pull request HTML URL" },
+    { name: "related_task_id", description: "ID of the related existing task" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.pull_request.mentioned",
+  header: "[GitHub PR #{{pr_number}}] {{pr_title}}",
+  defaultBody: `From: {{sender_login}}
+Repo: {{repo_full_name}}
+Branch: {{head_ref}} \u2192 {{base_ref}}
+URL: {{pr_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_pr]}}`,
+  variables: [
+    { name: "pr_number", description: "Pull request number" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "head_ref", description: "Head branch name" },
+    { name: "base_ref", description: "Base branch name" },
+    { name: "pr_url", description: "Pull request HTML URL" },
+    { name: "context", description: "Extracted mention context or PR title" },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Issue events
+// ============================================================================
+
+registerTemplate({
+  eventType: "github.issue.assigned",
+  header: "[GitHub Issue #{{issue_number}}] {{issue_title}}",
+  defaultBody: `Assigned to: @{{bot_name}}
+From: {{sender_login}}
+Repo: {{repo_full_name}}
+URL: {{issue_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_issue]}}`,
+  variables: [
+    { name: "issue_number", description: "Issue number" },
+    { name: "issue_title", description: "Issue title" },
+    { name: "bot_name", description: "GitHub bot username" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "issue_url", description: "Issue HTML URL" },
+    { name: "context", description: "Issue body or title as context" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.issue.mentioned",
+  header: "[GitHub Issue #{{issue_number}}] {{issue_title}}",
+  defaultBody: `From: {{sender_login}}
+Repo: {{repo_full_name}}
+URL: {{issue_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_issue]}}`,
+  variables: [
+    { name: "issue_number", description: "Issue number" },
+    { name: "issue_title", description: "Issue title" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "issue_url", description: "Issue HTML URL" },
+    { name: "context", description: "Extracted mention context or issue title" },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Comment events
+// ============================================================================
+
+registerTemplate({
+  eventType: "github.comment.mentioned",
+  header: "[GitHub {{target_type}} #{{target_number}} Comment] {{target_title}}",
+  defaultBody: `From: {{sender_login}}
+Repo: {{repo_full_name}}
+URL: {{comment_url}}
+
+Comment:
+{{context}}
+
+---
+{{related_task_section}}{{@template[common.delegation_instruction]}}
+{{command_suggestions}}`,
+  variables: [
+    { name: "target_type", description: "PR or Issue" },
+    { name: "target_number", description: "PR or issue number" },
+    { name: "target_title", description: "PR or issue title" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "comment_url", description: "Comment HTML URL" },
+    { name: "context", description: "Extracted mention context from comment" },
+    {
+      name: "related_task_section",
+      description: "Related task info with routing hint, or empty string if no related task",
+    },
+    { name: "command_suggestions", description: "Context-appropriate command suggestions" },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Pull Request Review events
+// ============================================================================
+
+registerTemplate({
+  eventType: "github.pull_request.review_submitted",
+  header: "{{review_emoji}} [GitHub PR #{{pr_number}} Review] {{review_label}}",
+  defaultBody: `PR: {{pr_title}}
+Reviewer: {{sender_login}}
+Repo: {{repo_full_name}}
+URL: {{review_url}}{{review_body_section}}
+
+---
+{{related_task_section}}{{@template[common.delegation_instruction]}}
+{{review_suggestions}}`,
+  variables: [
+    { name: "review_emoji", description: "Emoji for review state" },
+    { name: "pr_number", description: "Pull request number" },
+    { name: "review_label", description: "Review state label (APPROVED, CHANGES REQUESTED, etc.)" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "sender_login", description: "Reviewer login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "review_url", description: "Review HTML URL" },
+    { name: "review_body_section", description: "Review comment section or empty string" },
+    { name: "related_task_section", description: "Related task info or empty string" },
+    { name: "review_suggestions", description: "Context-appropriate review suggestion" },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// CI events
+// ============================================================================
+
+registerTemplate({
+  eventType: "github.check_run.failed",
+  header: "{{conclusion_emoji}} [GitHub PR #{{pr_number}} CI] {{check_name}} {{conclusion_label}}",
+  defaultBody: `Repo: {{repo_full_name}}
+Check: {{check_name}}
+URL: {{check_url}}{{output_summary_section}}
+
+---
+Related task: {{related_task_id}}
+\ud83d\udd00 Consider routing to the same agent working on the related task.
+\ud83d\udca1 CI check failed. Review the logs and fix the issue.`,
+  variables: [
+    { name: "conclusion_emoji", description: "Emoji for check conclusion" },
+    { name: "pr_number", description: "Pull request number" },
+    { name: "check_name", description: "Check run name" },
+    { name: "conclusion_label", description: "Conclusion label (FAILED, ACTION REQUIRED, etc.)" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "check_url", description: "Check run HTML URL" },
+    { name: "output_summary_section", description: "Output summary section or empty string" },
+    { name: "related_task_id", description: "ID of the related existing task" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.check_suite.failed",
+  header: "{{conclusion_emoji}} [GitHub PR #{{pr_number}} CI Suite] {{conclusion_label}}",
+  defaultBody: `Repo: {{repo_full_name}}
+Branch: {{branch}}
+Commit: {{head_sha_short}}
+
+---
+Related task: {{related_task_id}}
+\ud83d\udd00 Consider routing to the same agent working on the related task.
+\ud83d\udca1 CI suite failed. Check individual check runs for details.`,
+  variables: [
+    { name: "conclusion_emoji", description: "Emoji for check conclusion" },
+    { name: "pr_number", description: "Pull request number" },
+    { name: "conclusion_label", description: "Conclusion label" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "branch", description: "Head branch name" },
+    { name: "head_sha_short", description: "Short HEAD SHA (7 chars)" },
+    { name: "related_task_id", description: "ID of the related existing task" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "github.workflow_run.failed",
+  header:
+    "{{conclusion_emoji}} [GitHub PR #{{pr_number}} Workflow] {{workflow_run_name}} {{conclusion_label}}",
+  defaultBody: `Repo: {{repo_full_name}}
+Workflow: {{workflow_name}}
+Run #{{run_number}}
+Branch: {{head_branch}}
+Triggered by: {{trigger_event}}
+Logs: {{logs_url}}
+
+---
+Related task: {{related_task_id}}
+\ud83d\udd00 Consider routing to the same agent working on the related task.
+\ud83d\udca1 Workflow failed. Click the logs URL above to see what went wrong and fix the issue.`,
+  variables: [
+    { name: "conclusion_emoji", description: "Emoji for check conclusion" },
+    { name: "pr_number", description: "Pull request number" },
+    { name: "workflow_run_name", description: "Workflow run name" },
+    { name: "conclusion_label", description: "Conclusion label" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "workflow_name", description: "Workflow name" },
+    { name: "run_number", description: "Workflow run number" },
+    { name: "head_branch", description: "Head branch name" },
+    { name: "trigger_event", description: "Event that triggered the workflow" },
+    { name: "logs_url", description: "Workflow run logs URL" },
+    { name: "related_task_id", description: "ID of the related existing task" },
+  ],
+  category: "event",
+});

package/src/github/types.ts

@@ -17,6 +17,7 @@ export interface PullRequestEvent extends GitHubWebhookEvent {
     base: { ref: string };
     merged: boolean;
     merged_by?: { login: string };
+    changed_files?: number;
   };
   requested_reviewer?: { login: string; id: number }; // Added for review_requested/review_request_removed events
 }

package/src/gitlab/auth.ts

@@ -0,0 +1,63 @@
+/**
+ * GitLab Authentication & Webhook Verification
+ *
+ * GitLab uses a simple shared-secret token for webhook verification
+ * (X-Gitlab-Token header) and PAT/Group Access Token for API calls.
+ */
+
+let initialized = false;
+let webhookSecret: string | null = null;
+let apiToken: string | null = null;
+let gitlabUrl: string = "https://gitlab.com";
+
+export function isGitLabEnabled(): boolean {
+  return !!process.env.GITLAB_WEBHOOK_SECRET && process.env.GITLAB_DISABLE !== "true";
+}
+
+export function initGitLab(): void {
+  if (initialized) return;
+  if (!isGitLabEnabled()) {
+    console.log("[GitLab] Integration disabled (GITLAB_WEBHOOK_SECRET not set)");
+    return;
+  }
+
+  webhookSecret = process.env.GITLAB_WEBHOOK_SECRET!;
+  apiToken = process.env.GITLAB_TOKEN ?? null;
+  gitlabUrl = process.env.GITLAB_URL ?? "https://gitlab.com";
+  initialized = true;
+
+  console.log(`[GitLab] Integration initialized (url: ${gitlabUrl})`);
+}
+
+/**
+ * Verify a GitLab webhook request.
+ * GitLab uses simple string comparison of X-Gitlab-Token header against the configured secret.
+ */
+export function verifyGitLabWebhook(tokenHeader: string | undefined): boolean {
+  if (!webhookSecret) return false;
+  if (!tokenHeader) return false;
+  // timingSafeEqual throws on different lengths, so guard first
+  if (tokenHeader.length !== webhookSecret.length) return false;
+  return crypto.timingSafeEqual(Buffer.from(tokenHeader), Buffer.from(webhookSecret));
+}
+
+/** Get the GitLab API token for making API calls. */
+export function getGitLabToken(): string | null {
+  return apiToken;
+}
+
+/** Get the configured GitLab base URL. */
+export function getGitLabUrl(): string {
+  return gitlabUrl;
+}
+
+/** Bot name for mention detection. */
+export const GITLAB_BOT_NAME = process.env.GITLAB_BOT_NAME ?? "agent-swarm-bot";
+
+/** Reset state for testing. */
+export function resetGitLab(): void {
+  initialized = false;
+  webhookSecret = null;
+  apiToken = null;
+  gitlabUrl = "https://gitlab.com";
+}