@desplega.ai/agent-swarm 1.70.0 → 1.71.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.70.0",
+    "version": "1.71.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -6209,6 +6209,189 @@
         }
       }
     },
+    "/api/trackers/jira/authorize": {
+      "get": {
+        "summary": "Redirect to Atlassian OAuth consent screen",
+        "tags": [
+          "Trackers"
+        ],
+        "responses": {
+          "302": {
+            "description": "Redirect to Atlassian OAuth"
+          },
+          "500": {
+            "description": "Failed to generate authorization URL"
+          },
+          "503": {
+            "description": "Jira integration not configured"
+          }
+        }
+      }
+    },
+    "/api/trackers/jira/callback": {
+      "get": {
+        "summary": "Handle Jira OAuth callback (resolves cloudId via accessible-resources)",
+        "tags": [
+          "Trackers"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "code",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "state",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OAuth complete"
+          },
+          "400": {
+            "description": "Invalid state or code"
+          },
+          "500": {
+            "description": "Token exchange or accessible-resources fetch failed"
+          }
+        }
+      }
+    },
+    "/api/trackers/jira/status": {
+      "get": {
+        "summary": "Jira connection status, cloudId/siteUrl, token expiry, expected webhook URL, scope/token-config flags",
+        "tags": [
+          "Trackers"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Connection status"
+          },
+          "503": {
+            "description": "Jira integration not configured"
+          }
+        }
+      }
+    },
+    "/api/trackers/jira/webhook/{token}": {
+      "post": {
+        "summary": "Receive Jira webhook events (URL-token authenticated). Phase 2 stub — Phase 3 fills in dispatch.",
+        "tags": [
+          "Trackers"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "token",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Event accepted"
+          },
+          "401": {
+            "description": "Invalid URL token"
+          },
+          "503": {
+            "description": "Jira webhook handler not configured"
+          }
+        }
+      }
+    },
+    "/api/trackers/jira/webhook-register": {
+      "post": {
+        "summary": "Register a Jira dynamic webhook (admin only)",
+        "tags": [
+          "Trackers"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "jqlFilter": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "jqlFilter"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook registered"
+          },
+          "400": {
+            "description": "Invalid jqlFilter"
+          },
+          "503": {
+            "description": "Jira not connected or JIRA_WEBHOOK_TOKEN missing"
+          }
+        }
+      }
+    },
+    "/api/trackers/jira/webhook/{id}": {
+      "delete": {
+        "summary": "Delete a Jira dynamic webhook (admin only)",
+        "tags": [
+          "Trackers"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Webhook deleted"
+          },
+          "400": {
+            "description": "Invalid webhook id"
+          },
+          "503": {
+            "description": "Jira not connected"
+          }
+        }
+      }
+    },
     "/api/trackers/linear/authorize": {
       "get": {
         "summary": "Redirect to Linear OAuth consent screen",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.70.0",
+  "version": "1.71.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/be/db-queries/oauth.ts

@@ -39,9 +39,14 @@ export function upsertOAuthApp(
     metadata?: string;
   },
 ): void {
-  getDb()
-    .query(
-      `INSERT INTO oauth_apps (provider, clientId, clientSecret, authorizeUrl, tokenUrl, redirectUri, scopes, metadata)
+  // metadata is treated as a runtime-owned column (cloudId, webhookIds, etc.
+  // are written by OAuth callback + webhook-register flows). On INSERT we
+  // seed it with whatever the caller passed (or "{}"); on UPDATE we ONLY
+  // overwrite when the caller explicitly provided one — otherwise the
+  // existing value is preserved across server restarts.
+  const metadataProvided = data.metadata !== undefined;
+  const sql = metadataProvided
+    ? `INSERT INTO oauth_apps (provider, clientId, clientSecret, authorizeUrl, tokenUrl, redirectUri, scopes, metadata)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(provider) DO UPDATE SET
          clientId = excluded.clientId,
@@ -51,18 +56,43 @@ export function upsertOAuthApp(
          redirectUri = excluded.redirectUri,
          scopes = excluded.scopes,
          metadata = excluded.metadata,
-         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`,
-    )
-    .run(
-      provider,
-      data.clientId,
-      data.clientSecret,
-      data.authorizeUrl,
-      data.tokenUrl,
-      data.redirectUri,
-      data.scopes,
-      data.metadata ?? "{}",
-    );
+         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`
+    : `INSERT INTO oauth_apps (provider, clientId, clientSecret, authorizeUrl, tokenUrl, redirectUri, scopes, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, '{}')
+       ON CONFLICT(provider) DO UPDATE SET
+         clientId = excluded.clientId,
+         clientSecret = excluded.clientSecret,
+         authorizeUrl = excluded.authorizeUrl,
+         tokenUrl = excluded.tokenUrl,
+         redirectUri = excluded.redirectUri,
+         scopes = excluded.scopes,
+         updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+  if (metadataProvided) {
+    getDb()
+      .query(sql)
+      .run(
+        provider,
+        data.clientId,
+        data.clientSecret,
+        data.authorizeUrl,
+        data.tokenUrl,
+        data.redirectUri,
+        data.scopes,
+        data.metadata as string,
+      );
+  } else {
+    getDb()
+      .query(sql)
+      .run(
+        provider,
+        data.clientId,
+        data.clientSecret,
+        data.authorizeUrl,
+        data.tokenUrl,
+        data.redirectUri,
+        data.scopes,
+      );
+  }
 }
 
 // ── OAuth Tokens ──

package/src/be/db-queries/tracker.ts

@@ -41,6 +41,75 @@ export function getTrackerSyncByExternalId(
   return row ? normalizeTrackerSync(row) : null;
 }
 
+/**
+ * Idempotent UNIQUE-gated insert into `tracker_sync`. Returns
+ * `{ inserted: true, sync }` when a fresh row was created, or
+ * `{ inserted: false, sync }` when the `(provider, entityType, externalId)`
+ * tuple already had a row. Used by inbound webhook handlers (currently Jira)
+ * to gate task creation atomically: insert sync row first, only call
+ * `createTaskExtended` if `inserted === true`.
+ *
+ * Note: this is a "claim" insert — `swarmId` is initially the sentinel value
+ * passed in (callers typically pass a placeholder like `""` or a known UUID),
+ * then update it with `updateTrackerSyncSwarmId` once the task is created.
+ */
+export function createTrackerSyncIfAbsent(data: {
+  provider: string;
+  entityType: "task";
+  providerEntityType?: string | null;
+  swarmId: string;
+  externalId: string;
+  externalIdentifier?: string | null;
+  externalUrl?: string | null;
+  lastSyncOrigin?: "swarm" | "external" | null;
+  lastDeliveryId?: string | null;
+  syncDirection?: "inbound" | "outbound" | "bidirectional";
+}): { inserted: boolean; sync: TrackerSync } {
+  const insertResult = getDb()
+    .query(
+      `INSERT INTO tracker_sync (provider, entityType, providerEntityType, swarmId, externalId, externalIdentifier, externalUrl, lastSyncOrigin, lastDeliveryId, syncDirection)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (provider, entityType, externalId) DO NOTHING
+       RETURNING *`,
+    )
+    .get(
+      data.provider,
+      data.entityType,
+      data.providerEntityType ?? null,
+      data.swarmId,
+      data.externalId,
+      data.externalIdentifier ?? null,
+      data.externalUrl ?? null,
+      data.lastSyncOrigin ?? null,
+      data.lastDeliveryId ?? null,
+      data.syncDirection ?? "inbound",
+    ) as TrackerSync | null;
+
+  if (insertResult) {
+    return { inserted: true, sync: normalizeTrackerSync(insertResult) };
+  }
+
+  // Row already existed — fetch it for the caller.
+  const existing = getTrackerSyncByExternalId(data.provider, data.entityType, data.externalId);
+  if (!existing) {
+    // Should be unreachable: ON CONFLICT means a row exists, but this guard
+    // satisfies the type system and surfaces unexpected races loudly.
+    throw new Error(
+      `[tracker] createTrackerSyncIfAbsent: ON CONFLICT fired but no existing row found for (${data.provider}, ${data.entityType}, ${data.externalId})`,
+    );
+  }
+  return { inserted: false, sync: existing };
+}
+
+/**
+ * Update the `swarmId` on an existing `tracker_sync` row. Used after the
+ * idempotent `createTrackerSyncIfAbsent` returned `{ inserted: true }` and
+ * we've now created the swarm task that should own this row.
+ */
+export function updateTrackerSyncSwarmId(id: string, swarmId: string): void {
+  getDb().query("UPDATE tracker_sync SET swarmId = ? WHERE id = ?").run(swarmId, id);
+}
+
 export function createTrackerSync(data: {
   provider: string;
   entityType: "task";
@@ -128,6 +197,46 @@ export function deleteTrackerSync(id: string): void {
   getDb().query("DELETE FROM tracker_sync WHERE id = ?").run(id);
 }
 
+/**
+ * Check whether a `tracker_sync` row exists for `provider` with the given
+ * `lastDeliveryId`. Used by inbound webhook handlers (Jira) to dedupe
+ * deliveries via DB-persisted state instead of a process-local Map.
+ *
+ * Returns `false` when `deliveryId` is falsy/empty so callers don't have to
+ * branch.
+ */
+export function hasTrackerDelivery(
+  provider: string,
+  deliveryId: string | null | undefined,
+): boolean {
+  if (!deliveryId) return false;
+  const row = getDb()
+    .query("SELECT 1 AS hit FROM tracker_sync WHERE provider = ? AND lastDeliveryId = ? LIMIT 1")
+    .get(provider, deliveryId) as { hit: number } | null;
+  return !!row;
+}
+
+/**
+ * Mark a delivery as processed by writing `deliveryId` into the relevant
+ * `tracker_sync` row identified by `(provider, entityType, externalId)`.
+ *
+ * No-op when the row doesn't exist yet (the very first inbound event creates
+ * the row via `createTrackerSyncIfAbsent` — recording delivery happens after
+ * that). Caller is responsible for ordering.
+ */
+export function markTrackerDelivery(
+  provider: string,
+  entityType: "task",
+  externalId: string,
+  deliveryId: string,
+): void {
+  getDb()
+    .query(
+      "UPDATE tracker_sync SET lastDeliveryId = ? WHERE provider = ? AND entityType = ? AND externalId = ?",
+    )
+    .run(deliveryId, provider, entityType, externalId);
+}
+
 export function getAllTrackerSyncs(provider?: string, entityType?: "task"): TrackerSync[] {
   const conditions: string[] = [];
   const values: string[] = [];

package/src/be/migrations/043_jira_source.sql

@@ -0,0 +1,128 @@
+-- Add 'jira' to the agent_tasks.source CHECK constraint.
+-- SQLite cannot ALTER an existing CHECK; we follow the table-rebuild pattern
+-- (per migration 026). Column list mirrors the live post-042 schema verbatim
+-- — including all post-026 additions (credentialKeySuffix/Type, requestedByUserId,
+-- vcsInstallationId, vcsNodeId, slackReplySent, swarmVersion, contextKey).
+-- INSERT uses an explicit column list (no `SELECT *`) to be robust against
+-- column-order drift between SQLite versions.
+PRAGMA foreign_keys=off;
+
+CREATE TABLE agent_tasks_new (
+  id TEXT PRIMARY KEY,
+  agentId TEXT,
+  creatorAgentId TEXT,
+  task TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  source TEXT NOT NULL DEFAULT 'mcp' CHECK(source IN ('mcp', 'slack', 'api', 'github', 'gitlab', 'agentmail', 'system', 'schedule', 'workflow', 'linear', 'jira')),
+  taskType TEXT,
+  tags TEXT DEFAULT '[]',
+  priority INTEGER DEFAULT 50,
+  dependsOn TEXT DEFAULT '[]',
+  offeredTo TEXT,
+  offeredAt TEXT,
+  acceptedAt TEXT,
+  rejectionReason TEXT,
+  slackChannelId TEXT,
+  slackThreadTs TEXT,
+  slackUserId TEXT,
+  mentionMessageId TEXT,
+  mentionChannelId TEXT,
+  vcsProvider TEXT,
+  vcsRepo TEXT,
+  vcsEventType TEXT,
+  vcsNumber INTEGER,
+  vcsCommentId INTEGER,
+  vcsAuthor TEXT,
+  vcsUrl TEXT,
+  parentTaskId TEXT,
+  claudeSessionId TEXT,
+  agentmailInboxId TEXT,
+  agentmailMessageId TEXT,
+  agentmailThreadId TEXT,
+  model TEXT,
+  scheduleId TEXT,
+  workflowRunId TEXT REFERENCES workflow_runs(id),
+  workflowRunStepId TEXT REFERENCES workflow_run_steps(id),
+  createdAt TEXT NOT NULL,
+  lastUpdatedAt TEXT NOT NULL,
+  finishedAt TEXT,
+  failureReason TEXT,
+  output TEXT,
+  progress TEXT,
+  notifiedAt TEXT,
+  dir TEXT,
+  outputSchema TEXT,
+  compactionCount INTEGER DEFAULT 0,
+  peakContextPercent REAL,
+  totalContextTokensUsed INTEGER,
+  contextWindowSize INTEGER,
+  was_paused INTEGER NOT NULL DEFAULT 0,
+  credentialKeySuffix TEXT,
+  credentialKeyType TEXT,
+  requestedByUserId TEXT REFERENCES users(id),
+  vcsInstallationId INTEGER,
+  vcsNodeId TEXT,
+  slackReplySent INTEGER DEFAULT 0,
+  swarmVersion TEXT,
+  contextKey TEXT
+);
+
+INSERT INTO agent_tasks_new (
+  id, agentId, creatorAgentId, task, status, source, taskType, tags,
+  priority, dependsOn, offeredTo, offeredAt, acceptedAt, rejectionReason,
+  slackChannelId, slackThreadTs, slackUserId,
+  mentionMessageId, mentionChannelId,
+  vcsProvider, vcsRepo, vcsEventType, vcsNumber, vcsCommentId, vcsAuthor, vcsUrl,
+  parentTaskId, claudeSessionId,
+  agentmailInboxId, agentmailMessageId, agentmailThreadId,
+  model, scheduleId, workflowRunId, workflowRunStepId,
+  createdAt, lastUpdatedAt, finishedAt, failureReason, output, progress, notifiedAt,
+  dir, outputSchema, compactionCount, peakContextPercent,
+  totalContextTokensUsed, contextWindowSize, was_paused,
+  credentialKeySuffix, credentialKeyType, requestedByUserId,
+  vcsInstallationId, vcsNodeId, slackReplySent, swarmVersion, contextKey
+)
+SELECT
+  id, agentId, creatorAgentId, task, status, source, taskType, tags,
+  priority, dependsOn, offeredTo, offeredAt, acceptedAt, rejectionReason,
+  slackChannelId, slackThreadTs, slackUserId,
+  mentionMessageId, mentionChannelId,
+  vcsProvider, vcsRepo, vcsEventType, vcsNumber, vcsCommentId, vcsAuthor, vcsUrl,
+  parentTaskId, claudeSessionId,
+  agentmailInboxId, agentmailMessageId, agentmailThreadId,
+  model, scheduleId, workflowRunId, workflowRunStepId,
+  createdAt, lastUpdatedAt, finishedAt, failureReason, output, progress, notifiedAt,
+  dir, outputSchema, compactionCount, peakContextPercent,
+  totalContextTokensUsed, contextWindowSize, was_paused,
+  credentialKeySuffix, credentialKeyType, requestedByUserId,
+  vcsInstallationId, vcsNodeId, slackReplySent, swarmVersion, contextKey
+FROM agent_tasks;
+
+DROP TABLE agent_tasks;
+ALTER TABLE agent_tasks_new RENAME TO agent_tasks;
+
+-- Recreate every index that existed on agent_tasks (per `grep -rn "ON agent_tasks(" src/be/migrations/`):
+--   001/004/006/009/026: agentId, status, offeredTo, taskType, agentmailThreadId, scheduleId, workflowRunId
+--   031: requestedByUserId (partial)
+--   034: parentTaskId
+--   037: swarmVersion
+--   040: composite (slackChannelId, slackThreadTs, status)
+--   042: contextKey + (contextKey, status) composite
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_agentId ON agent_tasks(agentId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_status ON agent_tasks(status);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_offeredTo ON agent_tasks(offeredTo);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_taskType ON agent_tasks(taskType);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_agentmailThreadId ON agent_tasks(agentmailThreadId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_schedule_id ON agent_tasks(scheduleId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_workflow_run ON agent_tasks(workflowRunId);
+CREATE INDEX IF NOT EXISTS idx_tasks_requested_by ON agent_tasks(requestedByUserId) WHERE requestedByUserId IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_parentTaskId ON agent_tasks(parentTaskId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_swarmVersion ON agent_tasks(swarmVersion);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_slack_thread
+  ON agent_tasks(slackChannelId, slackThreadTs, status);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_context_key
+  ON agent_tasks(contextKey);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_context_key_status
+  ON agent_tasks(contextKey, status);
+
+PRAGMA foreign_keys=on;

package/src/commands/runner.ts

@@ -2207,8 +2207,13 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     configureHttpResolver(apiUrl, process.env.API_KEY);
   }
 
-  // Initialize anonymized telemetry (opt-out via ANONYMIZED_TELEMETRY=false)
-  // Workers use HTTP-based config access (cannot import DB directly)
+  // Initialize anonymized telemetry (opt-out via ANONYMIZED_TELEMETRY=false).
+  // Workers use HTTP-based config access (cannot import DB directly).
+  // IMPORTANT: workers must NOT pass `generateIfMissing` — the api-server is
+  // the sole authority for `telemetry_installation_id`. If the API hasn't
+  // persisted one yet (network blip, fresh boot, API down), the worker simply
+  // skips telemetry instead of minting a fresh `install_<hex>` ID per
+  // restart, which floods prod metrics with phantom installs.
   {
     const telemetryApiKey = process.env.API_KEY;
     await initTelemetry(

package/src/http/core.ts

@@ -11,32 +11,14 @@ import {
   updateAgentStatus,
 } from "../be/db";
 import { initGitHub, resetGitHub } from "../github";
+import { initJira, resetJira } from "../jira";
 import { initLinear, resetLinear } from "../linear";
 import { startSlackApp, stopSlackApp } from "../slack";
 import type { AgentStatus } from "../types";
 import { refreshSecretScrubberCache } from "../utils/secret-scrubber";
 import { generateOpenApiSpec, SCALAR_HTML } from "./openapi";
-import { routeRegistry } from "./route-def";
-import { agentWithCapacity, getPathSegments, matchRoute, parseQueryParams } from "./utils";
-
-/**
- * Check whether a request targets a route declared (via the `route()` factory)
- * with `auth: { apiKey: false }` — i.e. one that opts out of the API-key
- * bearer check. Handler files must use the `route()` factory for this to take
- * effect; unknown paths fail closed (auth required).
- */
-function isPublicRoute(method: string | undefined, pathSegments: string[]): boolean {
-  for (const def of routeRegistry) {
-    if (def.auth?.apiKey === false) {
-      if (
-        matchRoute(method, pathSegments, def.method.toUpperCase(), def.pattern, def.exact ?? true)
-      ) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
+import { isPublicRoute } from "./route-def";
+import { agentWithCapacity, getPathSegments, parseQueryParams } from "./utils";
 
 /**
  * Load global swarm_config entries into process.env.
@@ -88,6 +70,9 @@ export async function reloadGlobalConfigsAndIntegrations(): Promise<ReloadConfig
   resetLinear();
   if (initLinear()) integrations.push("linear");
 
+  resetJira();
+  if (initJira()) integrations.push("jira");
+
   await stopSlackApp();
   await startSlackApp();
   integrations.push("slack");

package/src/http/index.ts

@@ -12,6 +12,7 @@ import { closeDb, getSwarmConfigs, upsertSwarmConfig } from "../be/db";
 import { initGitHub } from "../github";
 import { initGitLab } from "../gitlab";
 import { stopHeartbeat } from "../heartbeat";
+import { initJira } from "../jira";
 import { initLinear } from "../linear";
 import { startSlackApp, stopSlackApp } from "../slack";
 import { initTelemetry, telemetry } from "../telemetry";
@@ -245,13 +246,17 @@ httpServer
       );
     }
 
-    // Initialize anonymized telemetry (opt-out via ANONYMIZED_TELEMETRY=false)
+    // Initialize anonymized telemetry (opt-out via ANONYMIZED_TELEMETRY=false).
+    // The api-server is the sole authority for the install identity — pass
+    // generateIfMissing so it mints a new install ID on first boot. Workers
+    // must NOT mint (see src/commands/runner.ts).
     await initTelemetry(
       "api-server",
       (key) => getSwarmConfigs({ scope: "global", key })?.[0]?.value,
       (key, value) => {
         upsertSwarmConfig({ scope: "global", key, value });
       },
+      { generateIfMissing: true },
     );
     telemetry.server("started", { port });
 
@@ -270,6 +275,9 @@ httpServer
     // Initialize Linear tracker integration (if configured)
     initLinear();
 
+    // Initialize Jira tracker integration (if configured)
+    initJira();
+
     // Initialize workflow engine (trigger subscriptions + resume listener)
     initWorkflows();
 

package/src/http/route-def.ts

@@ -60,6 +60,25 @@ interface RouteHandle<TParams, TQuery, TBody> {
 /** Global registry — populated at import time, read by OpenAPI generator */
 export const routeRegistry: RouteDef[] = [];
 
+/**
+ * Check whether a request targets a route declared (via the `route()` factory)
+ * with `auth: { apiKey: false }` — i.e. one that opts out of the API-key
+ * bearer check. Handler files must use the `route()` factory for this to take
+ * effect; unknown paths fail closed (auth required).
+ */
+export function isPublicRoute(method: string | undefined, pathSegments: string[]): boolean {
+  for (const def of routeRegistry) {
+    if (def.auth?.apiKey === false) {
+      if (
+        matchRoute(method, pathSegments, def.method.toUpperCase(), def.pattern, def.exact ?? true)
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 // ─── Factory ─────────────────────────────────────────────────────────────────
 
 export function route<

package/src/http/trackers/index.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { handleJiraTracker } from "./jira";
 import { handleLinearTracker } from "./linear";
 
 export async function handleTrackers(
@@ -6,5 +7,17 @@ export async function handleTrackers(
   res: ServerResponse,
   pathSegments: string[],
 ): Promise<boolean> {
+  // Provider-specific dispatch based on the third path segment
+  // (e.g. "api", "trackers", "<provider>", ...).
+  if (pathSegments[0] === "api" && pathSegments[1] === "trackers") {
+    if (pathSegments[2] === "jira") {
+      return await handleJiraTracker(req, res, pathSegments);
+    }
+    if (pathSegments[2] === "linear") {
+      return await handleLinearTracker(req, res, pathSegments);
+    }
+  }
+  // Fallback: try Linear (preserves existing behavior for any path that
+  // somehow falls through without an explicit provider segment).
   return await handleLinearTracker(req, res, pathSegments);
 }