@desplega.ai/agent-swarm 1.70.0 → 1.71.1

package/src/telemetry.ts

@@ -19,30 +19,51 @@ function isEnabled(): boolean {
   return process.env.ANONYMIZED_TELEMETRY !== "false";
 }
 
+interface InitTelemetryOptions {
+  /**
+   * Whether to mint and persist a new install ID when the config read returns
+   * nothing (or fails). Only the api-server should set this — it owns the
+   * install identity. Workers piggyback on whatever the api-server has
+   * persisted; if it's not there yet, the worker silently no-ops telemetry to
+   * avoid polluting metrics with ephemeral per-restart IDs.
+   *
+   * Default: false.
+   */
+  generateIfMissing?: boolean;
+}
+
 /**
  * Initialize telemetry. Call once at startup.
  * @param sourceId - "api-server" or "worker"
  * @param getConfig - reads a key from swarm_config (global scope)
  * @param setConfig - writes a key to swarm_config (global scope)
+ * @param options - see {@link InitTelemetryOptions}
  */
 export async function initTelemetry(
   sourceId: string,
   getConfig: (key: string) => Promise<string | undefined> | string | undefined,
   setConfig: (key: string, value: string) => Promise<void> | void,
+  options: InitTelemetryOptions = {},
 ): Promise<void> {
   if (!isEnabled()) return;
   source = sourceId;
+  const generateIfMissing = options.generateIfMissing === true;
   try {
     const existing = await getConfig("telemetry_installation_id");
     if (existing) {
       installationId = existing;
-    } else {
+    } else if (generateIfMissing) {
       installationId = `install_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
       await setConfig("telemetry_installation_id", installationId);
     }
+    // else: leave installationId = null; track() will no-op
   } catch {
-    // Config access failed — generate ephemeral ID so telemetry still works this session
-    installationId = `ephemeral_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+    // Config access failed.
+    if (generateIfMissing) {
+      // Generate ephemeral ID so telemetry still works this session.
+      installationId = `ephemeral_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+    }
+    // else: leave installationId = null; track() will no-op
   }
 }
 
@@ -82,6 +103,20 @@ export function track(options: TrackOptions): void {
   }
 }
 
+/**
+ * Test-only: reset the module-scoped state so tests can re-init cleanly.
+ * Do not call from production code.
+ */
+export function _resetTelemetryStateForTests(): void {
+  installationId = null;
+  source = "unknown";
+}
+
+/** Test-only: read the resolved install ID. */
+export function _getInstallationIdForTests(): string | null {
+  return installationId;
+}
+
 export const telemetry = {
   taskEvent(
     event: string,

package/src/tests/context-key.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   agentmailContextKey,
+  buildJiraContextKey,
   githubContextKey,
   gitlabContextKey,
   linearContextKey,
@@ -37,6 +38,10 @@ describe("context-key builders", () => {
     expect(linearContextKey({ issueIdentifier: "DES-42" })).toBe("task:trackers:linear:DES-42");
   });
 
+  test("buildJiraContextKey preserves identifier case", () => {
+    expect(buildJiraContextKey("PROJ-123")).toBe("task:trackers:jira:PROJ-123");
+  });
+
   test("scheduleContextKey builds expected format", () => {
     expect(scheduleContextKey({ scheduleId: "sched-uuid" })).toBe("task:schedule:sched-uuid");
   });
@@ -71,10 +76,15 @@ describe("context-key separator safety", () => {
     expect(() => linearContextKey({ issueIdentifier: "DES:42" })).toThrow(/must not contain/);
   });
 
+  test("buildJiraContextKey throws when identifier contains ':'", () => {
+    expect(() => buildJiraContextKey("PROJ:123")).toThrow(/must not contain/);
+  });
+
   test("throws on empty values", () => {
     expect(() => slackContextKey({ channelId: "", threadTs: "1" })).toThrow(/non-empty/);
     expect(() => agentmailContextKey({ threadId: "" })).toThrow(/non-empty/);
     expect(() => linearContextKey({ issueIdentifier: "" })).toThrow(/non-empty/);
+    expect(() => buildJiraContextKey("")).toThrow(/non-empty/);
   });
 
   test("githubContextKey validates kind", () => {
@@ -147,6 +157,15 @@ describe("parseContextKey", () => {
     });
   });
 
+  test("round-trips jira keys with case preserved", () => {
+    const key = buildJiraContextKey("PROJ-123");
+    expect(parseContextKey(key)).toEqual({
+      family: "trackers",
+      subFamily: "jira",
+      parts: { issueIdentifier: "PROJ-123" },
+    });
+  });
+
   test("round-trips schedule keys", () => {
     const key = scheduleContextKey({ scheduleId: "sched-1" });
     expect(parseContextKey(key)).toEqual({

package/src/tests/jira-adf.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, test } from "bun:test";
+import { extractMentions, extractText } from "../jira/adf";
+
+describe("jira/adf — extractText", () => {
+  test("returns empty string for non-node input", () => {
+    expect(extractText(null)).toBe("");
+    expect(extractText(undefined)).toBe("");
+    expect(extractText("not a node")).toBe("");
+    expect(extractText(42)).toBe("");
+  });
+
+  test("extracts plain text from a single paragraph", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "Hello world." }],
+        },
+      ],
+    };
+    expect(extractText(adf)).toBe("Hello world.");
+  });
+
+  test("joins text across multiple paragraphs with newlines", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "First." }] },
+        { type: "paragraph", content: [{ type: "text", text: "Second." }] },
+      ],
+    };
+    expect(extractText(adf)).toBe("First.\nSecond.");
+  });
+
+  test("inlines mentions as @<displayName>", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "Hi " },
+            {
+              type: "mention",
+              attrs: { id: "557058:abc-123", text: "@Bot User" },
+            },
+            { type: "text", text: " please look." },
+          ],
+        },
+      ],
+    };
+    // mention text "@Bot User" already has "@", normalizer keeps single "@"
+    expect(extractText(adf)).toBe("Hi @Bot User please look.");
+  });
+
+  test("falls back to accountId when mention has no display text", () => {
+    const adf = {
+      type: "paragraph",
+      content: [
+        { type: "text", text: "ping " },
+        { type: "mention", attrs: { id: "557058:xyz" } },
+      ],
+    };
+    expect(extractText(adf)).toBe("ping @557058:xyz");
+  });
+
+  test("handles bullet lists", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "bulletList",
+          content: [
+            {
+              type: "listItem",
+              content: [
+                {
+                  type: "paragraph",
+                  content: [{ type: "text", text: "alpha" }],
+                },
+              ],
+            },
+            {
+              type: "listItem",
+              content: [
+                {
+                  type: "paragraph",
+                  content: [{ type: "text", text: "beta" }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const out = extractText(adf);
+    expect(out).toContain("- alpha");
+    expect(out).toContain("- beta");
+  });
+
+  test("handles headings, codeBlock, blockquote, hardBreak", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "heading",
+          attrs: { level: 1 },
+          content: [{ type: "text", text: "Title" }],
+        },
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "line1" },
+            { type: "hardBreak" },
+            { type: "text", text: "line2" },
+          ],
+        },
+        {
+          type: "codeBlock",
+          content: [{ type: "text", text: "echo hi" }],
+        },
+        {
+          type: "blockquote",
+          content: [
+            {
+              type: "paragraph",
+              content: [{ type: "text", text: "quoted" }],
+            },
+          ],
+        },
+      ],
+    };
+    const out = extractText(adf);
+    expect(out).toContain("Title");
+    expect(out).toContain("line1\nline2");
+    expect(out).toContain("echo hi");
+    expect(out).toContain("quoted");
+  });
+
+  test("descends into unknown node content rather than dropping it", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "weird-custom-type",
+          content: [
+            {
+              type: "paragraph",
+              content: [{ type: "text", text: "still visible" }],
+            },
+          ],
+        },
+      ],
+    };
+    expect(extractText(adf)).toContain("still visible");
+  });
+});
+
+describe("jira/adf — extractMentions", () => {
+  test("returns empty array for non-node input", () => {
+    expect(extractMentions(null)).toEqual([]);
+    expect(extractMentions("string")).toEqual([]);
+  });
+
+  test("returns empty array when no mentions present", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "no mentions here" }],
+        },
+      ],
+    };
+    expect(extractMentions(adf)).toEqual([]);
+  });
+
+  test("collects accountIds from all mention nodes", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "mention", attrs: { id: "557058:a", text: "@Alice" } },
+            { type: "text", text: " and " },
+            { type: "mention", attrs: { id: "557058:b", text: "@Bob" } },
+          ],
+        },
+        {
+          type: "paragraph",
+          content: [{ type: "mention", attrs: { id: "557058:c", text: "@Carol" } }],
+        },
+      ],
+    };
+    expect(extractMentions(adf)).toEqual(["557058:a", "557058:b", "557058:c"]);
+  });
+
+  test("ignores mention nodes without a string id", () => {
+    const adf = {
+      type: "paragraph",
+      content: [
+        { type: "mention", attrs: { id: 123 } }, // wrong type
+        { type: "mention", attrs: {} }, // missing
+        { type: "mention", attrs: { id: "557058:ok", text: "@OK" } },
+      ],
+    };
+    expect(extractMentions(adf)).toEqual(["557058:ok"]);
+  });
+
+  test("descends into nested structures (lists, blockquotes)", () => {
+    const adf = {
+      type: "doc",
+      content: [
+        {
+          type: "bulletList",
+          content: [
+            {
+              type: "listItem",
+              content: [
+                {
+                  type: "paragraph",
+                  content: [
+                    {
+                      type: "mention",
+                      attrs: { id: "557058:nested", text: "@N" },
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    expect(extractMentions(adf)).toEqual(["557058:nested"]);
+  });
+});

package/src/tests/jira-metadata.test.ts

@@ -0,0 +1,147 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, getDb, initDb } from "../be/db";
+import { upsertOAuthApp } from "../be/db-queries/oauth";
+import { getJiraMetadata, updateJiraMetadata } from "../jira/metadata";
+
+const TEST_DB_PATH = "./test-jira-metadata.sqlite";
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(async () => {
+  closeDb();
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+});
+
+beforeEach(() => {
+  // Reset the oauth_apps row before each test so prior writes can't leak.
+  getDb().query("DELETE FROM oauth_apps WHERE provider = 'jira'").run();
+  upsertOAuthApp("jira", {
+    clientId: "client-id",
+    clientSecret: "client-secret",
+    authorizeUrl: "https://auth.atlassian.com/authorize",
+    tokenUrl: "https://auth.atlassian.com/oauth/token",
+    redirectUri: "http://localhost:3013/api/trackers/jira/callback",
+    scopes: "read:jira-work,write:jira-work,manage:jira-webhook,offline_access,read:me",
+  });
+});
+
+describe("getJiraMetadata", () => {
+  test("returns empty object when oauth_apps row is missing", () => {
+    getDb().query("DELETE FROM oauth_apps WHERE provider = 'jira'").run();
+    expect(getJiraMetadata()).toEqual({});
+  });
+
+  test("returns empty object when metadata is malformed JSON", () => {
+    getDb()
+      .query("UPDATE oauth_apps SET metadata = ? WHERE provider = 'jira'")
+      .run("{not valid json");
+    expect(getJiraMetadata()).toEqual({});
+  });
+
+  test("returns empty object when metadata is empty string", () => {
+    getDb().query("UPDATE oauth_apps SET metadata = ? WHERE provider = 'jira'").run("");
+    expect(getJiraMetadata()).toEqual({});
+  });
+
+  test("returns parsed cloudId/siteUrl/webhookIds when present", () => {
+    const meta = {
+      cloudId: "cloud-1",
+      siteUrl: "https://example.atlassian.net",
+      webhookIds: [{ id: 42, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = KAN" }],
+    };
+    getDb()
+      .query("UPDATE oauth_apps SET metadata = ? WHERE provider = 'jira'")
+      .run(JSON.stringify(meta));
+
+    const result = getJiraMetadata();
+    expect(result.cloudId).toBe("cloud-1");
+    expect(result.siteUrl).toBe("https://example.atlassian.net");
+    expect(result.webhookIds).toEqual([
+      { id: 42, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = KAN" },
+    ]);
+  });
+
+  test("filters malformed webhookIds entries", () => {
+    const meta = {
+      webhookIds: [
+        { id: 1, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = A" },
+        { id: "not-a-number", expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = B" },
+        { id: 2, expiresAt: 12345, jql: "project = C" }, // expiresAt wrong type
+        null,
+      ],
+    };
+    getDb()
+      .query("UPDATE oauth_apps SET metadata = ? WHERE provider = 'jira'")
+      .run(JSON.stringify(meta));
+
+    const result = getJiraMetadata();
+    expect(result.webhookIds).toEqual([
+      { id: 1, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = A" },
+    ]);
+  });
+});
+
+describe("updateJiraMetadata", () => {
+  test("scalar keys: shallow merge preserves untouched keys", () => {
+    updateJiraMetadata({ cloudId: "cloud-1", siteUrl: "https://example.atlassian.net" });
+    updateJiraMetadata({ cloudId: "cloud-2" });
+    const meta = getJiraMetadata();
+    expect(meta.cloudId).toBe("cloud-2");
+    expect(meta.siteUrl).toBe("https://example.atlassian.net");
+  });
+
+  test("webhookIds: id-keyed merge preserves untouched entries and replaces matching ids", () => {
+    updateJiraMetadata({
+      webhookIds: [
+        { id: 1, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = A" },
+        { id: 2, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = B" },
+      ],
+    });
+
+    // Update id=2 only — id=1 should be untouched.
+    updateJiraMetadata({
+      webhookIds: [{ id: 2, expiresAt: "2026-12-31T00:00:00.000Z", jql: "project = B-updated" }],
+    });
+
+    const meta = getJiraMetadata();
+    const sorted = [...(meta.webhookIds ?? [])].sort((a, b) => a.id - b.id);
+    expect(sorted).toEqual([
+      { id: 1, expiresAt: "2026-12-01T00:00:00.000Z", jql: "project = A" },
+      { id: 2, expiresAt: "2026-12-31T00:00:00.000Z", jql: "project = B-updated" },
+    ]);
+  });
+
+  test("concurrent-style updates preserve both writers' keys", () => {
+    // Phase 2 OAuth callback writes cloudId+siteUrl, Phase 5 webhook-register
+    // writes webhookIds. Both should coexist after both have run.
+    updateJiraMetadata({ cloudId: "cloud-x", siteUrl: "https://x.atlassian.net" });
+    updateJiraMetadata({
+      webhookIds: [{ id: 99, expiresAt: "2026-11-01T00:00:00.000Z", jql: "project = X" }],
+    });
+
+    const meta = getJiraMetadata();
+    expect(meta.cloudId).toBe("cloud-x");
+    expect(meta.siteUrl).toBe("https://x.atlassian.net");
+    expect(meta.webhookIds).toEqual([
+      { id: 99, expiresAt: "2026-11-01T00:00:00.000Z", jql: "project = X" },
+    ]);
+  });
+
+  test("throws when oauth_apps row for jira is missing", () => {
+    getDb().query("DELETE FROM oauth_apps WHERE provider = 'jira'").run();
+    expect(() => updateJiraMetadata({ cloudId: "x" })).toThrow(/oauth_apps row missing/);
+  });
+
+  test("undefined partial keys do not clobber existing values", () => {
+    updateJiraMetadata({ cloudId: "cloud-keep", siteUrl: "https://keep.atlassian.net" });
+    updateJiraMetadata({}); // No keys passed
+    const meta = getJiraMetadata();
+    expect(meta.cloudId).toBe("cloud-keep");
+    expect(meta.siteUrl).toBe("https://keep.atlassian.net");
+  });
+});

package/src/tests/jira-oauth.test.ts

@@ -0,0 +1,167 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, getDb, initDb } from "../be/db";
+import { upsertOAuthApp } from "../be/db-queries/oauth";
+import { getJiraMetadata } from "../jira/metadata";
+import * as wrapperModule from "../oauth/wrapper";
+
+const TEST_DB_PATH = "./test-jira-oauth.sqlite";
+
+// Spy on `exchangeCode` instead of `mock.module(...)` so the real wrapper
+// module remains untouched in the test process. mock.module is process-global
+// and not restorable per bun's docs ("mock.restore() does not reset the value
+// of modules that were overridden with mock.module()") — when this file ran
+// before src/tests/oauth-wrapper.test.ts in CI's order, the wrapper stayed
+// mocked and broke the wrapper's own unit tests.
+const exchangeCodeSpy = spyOn(wrapperModule, "exchangeCode");
+
+const originalFetch = globalThis.fetch;
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+  upsertOAuthApp("jira", {
+    clientId: "client-id",
+    clientSecret: "client-secret",
+    authorizeUrl: "https://auth.atlassian.com/authorize",
+    tokenUrl: "https://auth.atlassian.com/oauth/token",
+    redirectUri: "http://localhost:3013/api/trackers/jira/callback",
+    scopes: "read:jira-work",
+  });
+});
+
+afterAll(async () => {
+  globalThis.fetch = originalFetch;
+  mock.restore();
+  closeDb();
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+});
+
+const { handleJiraCallback } = await import("../jira/oauth");
+
+beforeEach(() => {
+  exchangeCodeSpy.mockClear();
+  exchangeCodeSpy.mockImplementation(() =>
+    Promise.resolve({
+      accessToken: "access-1",
+      refreshToken: "refresh-1",
+      expiresIn: 3600,
+      scope: "read:jira-work",
+    }),
+  );
+  // Wipe metadata between tests to confirm writes happen.
+  getDb().query("UPDATE oauth_apps SET metadata = '{}' WHERE provider = 'jira'").run();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("handleJiraCallback", () => {
+  test("exchanges code, fetches accessible-resources, persists cloudId+siteUrl", async () => {
+    let fetchedUrl: string | undefined;
+    let fetchedHeaders: Record<string, string> | undefined;
+    globalThis.fetch = mock((url: string, init?: RequestInit) => {
+      fetchedUrl = url;
+      fetchedHeaders = init?.headers as Record<string, string> | undefined;
+      return Promise.resolve(
+        new Response(
+          JSON.stringify([
+            {
+              id: "cloud-abc",
+              url: "https://example.atlassian.net",
+              name: "example",
+              scopes: ["read:jira-work"],
+            },
+          ]),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      );
+    }) as unknown as typeof fetch;
+
+    const result = await handleJiraCallback("code-1", "state-1");
+
+    // exchangeCode invoked with our config + code/state
+    expect(exchangeCodeSpy).toHaveBeenCalledTimes(1);
+    expect(result.accessToken).toBe("access-1");
+    expect(result.cloudId).toBe("cloud-abc");
+    expect(result.siteUrl).toBe("https://example.atlassian.net");
+
+    // accessible-resources URL hit with the right Authorization
+    expect(fetchedUrl).toBe("https://api.atlassian.com/oauth/token/accessible-resources");
+    expect(fetchedHeaders?.Authorization).toBe("Bearer access-1");
+
+    // Metadata persisted via updateJiraMetadata
+    const meta = getJiraMetadata();
+    expect(meta.cloudId).toBe("cloud-abc");
+    expect(meta.siteUrl).toBe("https://example.atlassian.net");
+  });
+
+  test("throws cleanly when accessible-resources is empty", async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        new Response("[]", { status: 200, headers: { "Content-Type": "application/json" } }),
+      ),
+    ) as unknown as typeof fetch;
+
+    await expect(handleJiraCallback("code-2", "state-2")).rejects.toThrow(
+      /no accessible resources/i,
+    );
+
+    // Metadata not persisted
+    const meta = getJiraMetadata();
+    expect(meta.cloudId).toBeUndefined();
+  });
+
+  test("throws cleanly when accessible-resources is non-200", async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(new Response("oops", { status: 500 })),
+    ) as unknown as typeof fetch;
+
+    await expect(handleJiraCallback("code-3", "state-3")).rejects.toThrow(
+      /accessible-resources fetch failed/i,
+    );
+  });
+
+  test("throws when accessible-resources entry is malformed (missing id/url)", async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        new Response(JSON.stringify([{ name: "no-id" }]), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      ),
+    ) as unknown as typeof fetch;
+
+    await expect(handleJiraCallback("code-4", "state-4")).rejects.toThrow(/malformed entry/i);
+  });
+
+  test("picks the FIRST accessible resource (single-workspace v1 contract)", async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify([
+            { id: "cloud-first", url: "https://first.atlassian.net" },
+            { id: "cloud-second", url: "https://second.atlassian.net" },
+          ]),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      ),
+    ) as unknown as typeof fetch;
+
+    const result = await handleJiraCallback("code-5", "state-5");
+    expect(result.cloudId).toBe("cloud-first");
+    expect(result.siteUrl).toBe("https://first.atlassian.net");
+  });
+});