@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/azure-devops/handlers.ts

@@ -10,7 +10,12 @@
 
 import { findTaskByVcs, getAllAgents, incrKv, upsertKv } from "../be/db";
 import { renderIdentity, resolveIdentity } from "../be/identity";
-import { findOrCreateUserByEmail, findUserByExternalId, linkIdentity } from "../be/users";
+import {
+  findOrCreateUserByEmail,
+  findUserByEmail,
+  findUserByExternalId,
+  linkIdentity,
+} from "../be/users";
 import { resolveTemplate } from "../prompts/resolver";
 import { azureDevOpsContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
@@ -36,7 +41,7 @@ type HandlerResult = { created: boolean; taskId?: string };
 const processedEvents = new Map<string, number>();
 const DEDUP_TTL_MS = 60_000;
 
-function isDuplicate(key: string): boolean {
+export function isDuplicate(key: string): boolean {
   const now = Date.now();
   // Cleanup expired
   for (const [k, ts] of processedEvents) {
@@ -49,7 +54,7 @@ function isDuplicate(key: string): boolean {
 
 // ── Helpers ──
 
-function escapeRegExp(value: string): string {
+export function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
@@ -143,13 +148,15 @@ export function commentedPayloadOf(
   return { comment, pullRequest };
 }
 
-function warnMalformed(event: { eventType?: string; resourceVersion?: string } | null | undefined) {
+export function warnMalformed(
+  event: { eventType?: string; resourceVersion?: string } | null | undefined,
+) {
   console.warn(
     `[AzureDevOps] Ignoring ${event?.eventType} event with resourceVersion ${event?.resourceVersion ?? "unknown"}: required resource fields are missing`,
   );
 }
 
-async function findLeadAgent() {
+export async function findLeadAgent() {
   const agents = await getAllAgents();
   return (
     agents.find((a) => a.role === "lead" && a.status === "idle") ??
@@ -173,7 +180,7 @@ function externalIdOf(identity: AzureDevOpsIdentityRef): string {
  * linked identity (`uniqueName`) → email when `uniqueName` is one → unmapped
  * tracker entry for operator triage.
  */
-async function resolveAzureDevOpsSender(
+export async function resolveAzureDevOpsSender(
   identity: AzureDevOpsIdentityRef,
   sampleEventType: string,
   sampleContext: string,
@@ -192,6 +199,15 @@ async function resolveAzureDevOpsSender(
     return linked.id;
   }
 
+  await recordUnmappedIdentity(externalId, sampleEventType, sampleContext);
+  return undefined;
+}
+
+async function recordUnmappedIdentity(
+  externalId: string,
+  sampleEventType: string,
+  sampleContext: string,
+): Promise<void> {
   await upsertKv({
     namespace: UNMAPPED_NAMESPACE,
     key: `${externalId}:meta`,
@@ -204,14 +220,42 @@ async function resolveAzureDevOpsSender(
     expiresAt: Date.now() + UNMAPPED_TTL_MS,
   });
   await incrKv(UNMAPPED_NAMESPACE, `${externalId}:count`, 1);
-  return undefined;
+}
+
+/**
+ * Authorize an actor to trigger a task: a swarm user already linked to the
+ * identity (or owning its sign-in email), or a sign-in name listed in
+ * AZURE_DEVOPS_ALLOWED_ACTORS (comma-separated). Unlike
+ * `resolveAzureDevOpsSender` this never creates users for strangers. Returns
+ * the `users.id`, or null after recording the actor for operator triage.
+ */
+export async function authorizeAzureDevOpsActor(
+  identity: AzureDevOpsIdentityRef,
+  sampleEventType: string,
+  sampleContext: string,
+): Promise<string | null> {
+  const externalId = externalIdOf(identity);
+  const known =
+    (await findUserByExternalId("azure-devops", externalId)) ??
+    (externalId.includes("@") ? await findUserByEmail(externalId) : null);
+  if (known) return known.id;
+
+  const allowed = (process.env.AZURE_DEVOPS_ALLOWED_ACTORS ?? "")
+    .split(",")
+    .map((name) => name.trim().toLowerCase())
+    .filter(Boolean);
+  if (allowed.includes(externalId.toLowerCase())) {
+    return (await resolveAzureDevOpsSender(identity, sampleEventType, sampleContext)) ?? null;
+  }
+  await recordUnmappedIdentity(externalId, sampleEventType, sampleContext);
+  return null;
 }
 
 /**
  * Render an Azure DevOps identity for agent-visible text: the resolved
  * canonical name or the explicit UNKNOWN sentinel.
  */
-async function renderAzureDevOpsIdentity(identity: AzureDevOpsIdentityRef): Promise<string> {
+export async function renderAzureDevOpsIdentity(identity: AzureDevOpsIdentityRef): Promise<string> {
   return renderIdentity(await resolveIdentity("azure-devops", externalIdOf(identity)));
 }
 

package/src/azure-devops/html.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal HTML helpers for Azure Boards text. Work-item descriptions and
+ * comments are HTML; prompts want plain text.
+ */
+
+const ENTITIES: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&nbsp;": " ",
+};
+
+/** Strip tags, decode the common entities, and collapse whitespace. */
+export function htmlToText(html: string | null | undefined): string {
+  if (!html) return "";
+  return html
+    .replace(/<br\s*\/?>|<\/(?:div|p|li|h[1-6])>/gi, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&(?:amp|lt|gt|quot|#39|nbsp);/g, (entity) => ENTITIES[entity] ?? entity)
+    .replace(/[ \t]+/g, " ")
+    .replace(/ ?\n ?/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}

package/src/azure-devops/index.ts

@@ -4,6 +4,7 @@ export {
   postAzureDevOpsPullRequestComment,
   resetAzureDevOpsBotIdCache,
   resolveAzureDevOpsBotId,
+  resolveAzureDevOpsBotUniqueName,
 } from "./api";
 export {
   AZURE_DEVOPS_BOT_NAME,
@@ -14,6 +15,15 @@ export {
   resetAzureDevOps,
   verifyAzureDevOpsWebhook,
 } from "./auth";
+export {
+  handleWorkItemCommented,
+  handleWorkItemCreated,
+  handleWorkItemDeleted,
+  handleWorkItemRestored,
+  handleWorkItemUpdated,
+  updatedPayloadOf,
+  workItemOf,
+} from "./boards-sync";
 export {
   commentedPayloadOf,
   createdPullRequestOf,
@@ -24,4 +34,9 @@ export type {
   AzureDevOpsWebhookEvent,
   PullRequestCommentedEvent,
   PullRequestCreatedEvent,
+  WorkItemCommentedEvent,
+  WorkItemCreatedEvent,
+  WorkItemDeletedEvent,
+  WorkItemRestoredEvent,
+  WorkItemUpdatedEvent,
 } from "./types";

package/src/azure-devops/templates.ts

@@ -106,3 +106,89 @@ Comment:
   ],
   category: "event",
 });
+
+// ============================================================================
+// Azure Boards work-item events
+// ============================================================================
+
+registerTemplate({
+  eventType: "common.command_suggestions.azure_devops_work_item",
+  header: "",
+  defaultBody:
+    'Workers have the `az` CLI with the azure-devops extension, authenticated with the swarm PAT. Inspect the work item with `az boards work-item show --id {{work_item_id}}`. To reply on it, run `az boards work-item update --id {{work_item_id}} --discussion "<reply>"`.',
+  variables: [{ name: "work_item_id", description: "Work item ID" }],
+  category: "common",
+});
+
+const WORK_ITEM_VARIABLES = [
+  { name: "work_item_id", description: "Work item ID" },
+  { name: "work_item_type", description: "Work item type (Task, Bug, Issue, ...)" },
+  { name: "title", description: "Work item title" },
+  { name: "state", description: "Work item state" },
+  { name: "project", description: "Azure DevOps project name" },
+  { name: "work_item_url", description: "Work item web URL" },
+  {
+    name: "username",
+    description:
+      "Actor identity — resolved canonical name (e.g. 'Luis (azure-devops:luis@example.com)') or the UNKNOWN sentinel",
+  },
+];
+
+registerTemplate({
+  eventType: "azure-devops.work_item.assigned",
+  header: "[Azure DevOps {{work_item_type}} #{{work_item_id}}] {{title}}",
+  defaultBody: `Project: {{project}}
+State: {{state}}
+Triggered by: {{username}} ({{trigger}})
+URL: {{work_item_url}}
+
+{{description_section}}{{@template[common.command_suggestions.azure_devops_work_item]}}{{@template[common.delegation_instruction.azure_devops]}}`,
+  variables: [
+    ...WORK_ITEM_VARIABLES,
+    { name: "trigger", description: "Why the task was created (assigned to the bot, mentioned)" },
+    {
+      name: "description_section",
+      description: "Description section (HTML stripped) or empty string",
+    },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "azure-devops.work_item.commented",
+  header: "[Azure DevOps {{work_item_type}} #{{work_item_id}}] {{username}} mentioned bot",
+  defaultBody: `Project: {{project}}
+Title: {{title}}
+State: {{state}}
+URL: {{work_item_url}}
+
+Comment:
+{{context}}{{existing_task_note}}
+
+{{@template[common.command_suggestions.azure_devops_work_item]}}{{@template[common.delegation_instruction.azure_devops]}}`,
+  variables: [
+    ...WORK_ITEM_VARIABLES,
+    { name: "context", description: "Comment text with the bot mention removed" },
+    { name: "existing_task_note", description: "Note about an active task, or empty string" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "azure-devops.work_item.followup",
+  header: "[Azure DevOps {{work_item_type}} #{{work_item_id}}] Follow-up: {{title}}",
+  defaultBody: `Project: {{project}}
+State: {{state}}
+Trigger: {{trigger}} by {{username}}
+URL: {{work_item_url}}
+
+{{user_message}}
+
+{{@template[common.command_suggestions.azure_devops_work_item]}}{{@template[common.delegation_instruction.azure_devops]}}`,
+  variables: [
+    ...WORK_ITEM_VARIABLES,
+    { name: "trigger", description: "What re-engaged the swarm" },
+    { name: "user_message", description: "Comment text, or empty string" },
+  ],
+  category: "event",
+});

package/src/azure-devops/types.ts

@@ -87,4 +87,68 @@ export type PullRequestCommentedEvent = ServiceHookEvent<
   { comment: AzureDevOpsComment; pullRequest: AzureDevOpsPullRequest }
 >;
 
-export type AzureDevOpsWebhookEvent = PullRequestCreatedEvent | PullRequestCommentedEvent;
+/**
+ * Azure Boards work-item fields (`resource.fields` on created / commented /
+ * deleted / restored, `resource.revision.fields` on updated). Identities are
+ * strings of the form `"Display Name <unique@name>"`, not identity objects.
+ */
+export interface AzureDevOpsWorkItemFields {
+  "System.TeamProject"?: string;
+  "System.WorkItemType"?: string;
+  "System.State"?: string;
+  "System.Title"?: string;
+  "System.Description"?: string; // HTML
+  "System.AssignedTo"?: string;
+  "System.ChangedBy"?: string;
+  "System.History"?: string; // HTML of the latest comment (commented events only)
+  [field: string]: unknown;
+}
+
+/** `resource` of created / commented / deleted / restored events. */
+export interface AzureDevOpsWorkItem {
+  id: number;
+  rev: number;
+  fields: AzureDevOpsWorkItemFields;
+  url?: string;
+  /** Present on `workitem.commented`: identifies the comment and its edit version. */
+  commentVersionRef?: { commentId: number; version: number };
+}
+
+/**
+ * `resource` of `workitem.updated`. `id` is the update id; the work item is
+ * `workItemId`. `fields` holds only the changed fields; the full state is in
+ * `revision.fields`.
+ */
+export interface AzureDevOpsWorkItemUpdate {
+  id: number;
+  workItemId: number;
+  rev: number;
+  url?: string;
+  revisedBy: AzureDevOpsIdentityRef;
+  fields?: Record<string, { oldValue?: unknown; newValue?: unknown }>;
+  revision: { id: number; rev: number; fields: AzureDevOpsWorkItemFields };
+}
+
+/** `workitem.created` */
+export type WorkItemCreatedEvent = ServiceHookEvent<"workitem.created", AzureDevOpsWorkItem>;
+
+/** `workitem.updated` */
+export type WorkItemUpdatedEvent = ServiceHookEvent<"workitem.updated", AzureDevOpsWorkItemUpdate>;
+
+/** `workitem.commented`: `commentVersionRef.commentId` identifies the comment. */
+export type WorkItemCommentedEvent = ServiceHookEvent<"workitem.commented", AzureDevOpsWorkItem>;
+
+/** `workitem.deleted`: `resource.url` points at the recycle bin. */
+export type WorkItemDeletedEvent = ServiceHookEvent<"workitem.deleted", AzureDevOpsWorkItem>;
+
+/** `workitem.restored` */
+export type WorkItemRestoredEvent = ServiceHookEvent<"workitem.restored", AzureDevOpsWorkItem>;
+
+export type AzureDevOpsWebhookEvent =
+  | PullRequestCreatedEvent
+  | PullRequestCommentedEvent
+  | WorkItemCreatedEvent
+  | WorkItemUpdatedEvent
+  | WorkItemCommentedEvent
+  | WorkItemDeletedEvent
+  | WorkItemRestoredEvent;

package/src/be/config-refs.ts

@@ -0,0 +1,60 @@
+/**
+ * Config references: `{ "$config": "KEY" }` leaves inside a JSON config value
+ * that point at another config key (usually a secret). Pure, no DB access: the
+ * caller supplies the lookup and decides which keys are allowed.
+ */
+
+export interface ConfigRef {
+  $config: string;
+}
+
+/** True when `value` is exactly `{ "$config": "<non-empty string>" }`. */
+export function isConfigRef(value: unknown): value is ConfigRef {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  const ref = (value as { $config?: unknown }).$config;
+  return keys.length === 1 && keys[0] === "$config" && typeof ref === "string" && ref.length > 0;
+}
+
+export class ConfigRefError extends Error {
+  constructor(
+    message: string,
+    readonly missingKeys: string[],
+  ) {
+    super(message);
+    this.name = "ConfigRefError";
+  }
+}
+
+/**
+ * Replace every `{ "$config": "KEY" }` leaf in `value` with `lookup(KEY)`.
+ * Walks arrays and plain objects. Missing keys (lookup returns undefined) are
+ * collected and reported in one error. A lookup that throws (for example on a
+ * forbidden key) propagates as-is.
+ */
+export function resolveConfigRefs<T>(
+  value: unknown,
+  lookup: (key: string) => string | undefined,
+): T {
+  const missing = new Set<string>();
+
+  const walk = (node: unknown): unknown => {
+    if (isConfigRef(node)) {
+      const resolved = lookup(node.$config);
+      if (resolved === undefined) missing.add(node.$config);
+      return resolved;
+    }
+    if (Array.isArray(node)) return node.map(walk);
+    if (node !== null && typeof node === "object") {
+      return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));
+    }
+    return node;
+  };
+
+  const result = walk(value);
+  if (missing.size > 0) {
+    const keys = [...missing].sort();
+    throw new ConfigRefError(`Unresolved config reference(s): ${keys.join(", ")}`, keys);
+  }
+  return result as T;
+}

package/src/be/db/page-versions.ts

@@ -0,0 +1,15 @@
+import { getDbClient } from "./runtime";
+
+/**
+ * The page's edit counter, `MAX(page_versions.version) + 1`, or 1 before the
+ * first snapshot. Reads one indexed aggregate instead of every snapshot body:
+ * loading all versions of a large, often-edited page blocked the event loop
+ * for seconds per call.
+ */
+export async function getPageEditCounter(pageId: string): Promise<number> {
+  const row = await getDbClient().get<{ latest: number | null }>(
+    "SELECT MAX(version) AS latest FROM page_versions WHERE pageId = ?",
+    [pageId],
+  );
+  return (row?.latest ?? 0) + 1;
+}

package/src/be/db/runtime.ts

@@ -104,7 +104,34 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   db = new Database(dbPath, { create: true });
   console.log(`Database initialized at ${dbPath}`);
 
-  const database = db;
+  // Boot must finish before getDb() hands this handle out. A step below can
+  // throw SQLITE_BUSY while another connection holds the file, and the
+  // db-client retries BUSY by calling getDb() again. With `db` still assigned,
+  // that retry got a connection whose encryption key was never resolved, and
+  // the server died on "Encryption key not resolved yet". Drop the handle so
+  // the retry runs boot again.
+  const opened = db;
+  try {
+    return bootOpenedDb(opened, dbPath, resolvePromptTemplate, autoEncryptLegacyPlaintextSecrets);
+  } catch (error) {
+    if (db === opened) {
+      db = null;
+      try {
+        opened.close();
+      } catch {
+        // Already closed by the step that failed.
+      }
+    }
+    throw error;
+  }
+}
+
+function bootOpenedDb(
+  database: Database,
+  dbPath: string,
+  resolvePromptTemplate: typeof import("../db").resolvePromptTemplate,
+  autoEncryptLegacyPlaintextSecrets: typeof import("../db").autoEncryptLegacyPlaintextSecrets,
+): Database {
   database.run("PRAGMA journal_mode = WAL;");
   database.run("PRAGMA busy_timeout = 5000;");
   database.run("PRAGMA foreign_keys = ON;");
@@ -140,7 +167,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   // Old databases have CHECK(status IN ('pending','in_progress','completed','failed'))
   // which blocks 'cancelled', 'paused', 'offered', 'unassigned' statuses
   try {
-    const taskSchemaInfo = db
+    const taskSchemaInfo = database
       .prepare<{ sql: string | null }, []>(
         "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'agent_tasks'",
       )
@@ -153,7 +180,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
 
     if (needsStatusMigration) {
       console.log("[Migration] Removing restrictive CHECK constraint on agent_tasks.status");
-      db.run("PRAGMA foreign_keys=off");
+      database.run("PRAGMA foreign_keys=off");
 
       // Migrations run before this compatibility guard, so a legacy table now
       // carries every current column. Rebuilding from an old hard-coded column
@@ -169,12 +196,12 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
       if (rebuiltSchemaSql === schemaSql || !/agent_tasks_new/i.test(rebuiltSchemaSql)) {
         throw new Error("Could not derive agent_tasks schema without legacy status CHECK");
       }
-      const columns = db
+      const columns = database
         .prepare<{ name: string }, []>('PRAGMA table_info("agent_tasks")')
         .all()
         .map((column) => `"${column.name.replaceAll('"', '""')}"`)
         .join(", ");
-      const schemaObjects = db
+      const schemaObjects = database
         .prepare<{ sql: string }, []>(
           `SELECT sql FROM sqlite_master
            WHERE tbl_name = 'agent_tasks'
@@ -194,13 +221,13 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
         for (const sql of schemaObjects) database.run(sql);
       })();
 
-      db.run("PRAGMA foreign_keys=on");
+      database.run("PRAGMA foreign_keys=on");
       console.log("[Migration] Successfully removed CHECK constraint on agent_tasks.status");
     }
   } catch (e) {
     console.error("[Migration] Failed to update agent_tasks CHECK constraint:", e);
     try {
-      db.run("PRAGMA foreign_keys=on");
+      database.run("PRAGMA foreign_keys=on");
     } catch (cleanupError) {
       console.error("[Migration] Failed to re-enable SQLite foreign_keys pragma:", cleanupError);
     }
@@ -291,7 +318,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
     throw err;
   }
 
-  return db;
+  return database;
 }
 
 export function getDb(path?: string): Database {

package/src/be/db/skill-name-resolution.ts

@@ -0,0 +1,36 @@
+import { getDbClient } from "./runtime";
+
+export type SwarmSkillNameResolution =
+  | { kind: "found"; skillId: string }
+  | { kind: "ambiguous"; skillIds: string[] }
+  | { kind: "none" };
+
+/**
+ * Resolve a swarm-scope skill name for `skill-get`.
+ *
+ * Migration 019 makes a name unique only per scope + owner, so a swarm name can
+ * match one ownerless row plus any number of agent-owned rows. Precedence:
+ * the ownerless row, then the caller's own row, then a single owned row.
+ * Several foreign-owned rows are ambiguous; the caller must pass a skillId.
+ *
+ * `getSkillByName(name, "swarm")` stays ownerless-only: the seeder relies on it.
+ */
+export async function resolveSwarmSkillByName(
+  name: string,
+  callerAgentId?: string,
+): Promise<SwarmSkillNameResolution> {
+  const rows = await getDbClient().query<{ id: string; ownerAgentId: string | null }>(
+    "SELECT id, ownerAgentId FROM skills WHERE name = ? AND scope = 'swarm' ORDER BY createdAt, id",
+    [name],
+  );
+
+  const ownerless = rows.find((row) => !row.ownerAgentId);
+  if (ownerless) return { kind: "found", skillId: ownerless.id };
+
+  const own = callerAgentId ? rows.find((row) => row.ownerAgentId === callerAgentId) : undefined;
+  if (own) return { kind: "found", skillId: own.id };
+
+  if (rows.length === 1) return { kind: "found", skillId: rows[0]!.id };
+  if (rows.length > 1) return { kind: "ambiguous", skillIds: rows.map((row) => row.id) };
+  return { kind: "none" };
+}