@desplega.ai/agent-swarm 1.70.0 → 1.71.1

package/src/jira/webhook-lifecycle.ts

@@ -0,0 +1,363 @@
+import { jiraFetch } from "./client";
+import { getJiraMetadata, updateJiraMetadata } from "./metadata";
+
+const TWELVE_HOURS_MS = 12 * 60 * 60 * 1000;
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Atlassian dynamic webhooks expire 30 days after registration / refresh. We
+ * default to that on register and let the keepalive tighten the value on the
+ * first refresh round-trip (Atlassian returns the authoritative expiry).
+ */
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+const SLACK_ALERTS_CHANNEL = process.env.SLACK_ALERTS_CHANNEL || "C08JCRURPBV";
+
+const WEBHOOK_EVENTS = [
+  "jira:issue_updated",
+  "jira:issue_deleted",
+  "comment_created",
+  "comment_updated",
+] as const;
+
+let keepaliveInterval: ReturnType<typeof setInterval> | null = null;
+
+// ─── URL helpers ─────────────────────────────────────────────────────────────
+
+function getWebhookBaseUrl(): string {
+  return process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+}
+
+function getRegisteredWebhookUrl(): string {
+  const token = process.env.JIRA_WEBHOOK_TOKEN;
+  if (!token) {
+    throw new Error(
+      "JIRA_WEBHOOK_TOKEN is not set — webhook registration would produce an unauthenticatable URL.",
+    );
+  }
+  return `${getWebhookBaseUrl()}/api/trackers/jira/webhook/${token}`;
+}
+
+// ─── Slack alert (best-effort) ───────────────────────────────────────────────
+
+async function notifySlack(text: string): Promise<void> {
+  try {
+    const { getSlackApp } = await import("../slack/app");
+    const app = getSlackApp();
+    if (!app) {
+      console.warn("[Jira webhook keepalive] Slack not available, cannot send notification");
+      return;
+    }
+    await app.client.chat.postMessage({
+      channel: SLACK_ALERTS_CHANNEL,
+      text,
+    });
+    console.log("[Jira webhook keepalive] Slack notification sent");
+  } catch (slackErr) {
+    console.error(
+      "[Jira webhook keepalive] Failed to send Slack notification:",
+      slackErr instanceof Error ? slackErr.message : slackErr,
+    );
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export interface RegisterJiraWebhookResult {
+  webhookId: number;
+  expiresAt: string;
+  jql: string;
+}
+
+/**
+ * Register a dynamic webhook with Atlassian.
+ *
+ * The registered URL embeds `JIRA_WEBHOOK_TOKEN` in the path so inbound
+ * deliveries can be authenticated (Atlassian does not HMAC-sign OAuth 3LO
+ * dynamic webhooks — see plan errata I8).
+ *
+ * Atlassian's response shape:
+ *   { webhookRegistrationResult: [{ createdWebhookId: number, errors?: string[] }] }
+ *
+ * The response does NOT include the expiry on registration — we default to
+ * `now + 30 days` (the documented webhook lifetime) and let the first refresh
+ * tick replace it with Atlassian's authoritative `expirationDate`.
+ */
+export async function registerJiraWebhook(jqlFilter: string): Promise<RegisterJiraWebhookResult> {
+  const url = getRegisteredWebhookUrl();
+
+  const response = await jiraFetch("/rest/api/3/webhook", {
+    method: "POST",
+    body: JSON.stringify({
+      url,
+      webhooks: [
+        {
+          events: WEBHOOK_EVENTS,
+          jqlFilter,
+          fieldIdsFilter: ["assignee"],
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => "");
+    throw new Error(`Jira webhook registration failed (${response.status}): ${errorText}`);
+  }
+
+  const payload = (await response.json()) as {
+    webhookRegistrationResult?: Array<{
+      createdWebhookId?: number;
+      errors?: string[];
+    }>;
+  };
+
+  const results = payload.webhookRegistrationResult ?? [];
+  if (results.length === 0) {
+    throw new Error(
+      "Jira webhook registration returned no results — payload may have been rejected upstream",
+    );
+  }
+
+  const first = results[0];
+  if (!first || typeof first.createdWebhookId !== "number") {
+    const errors = first?.errors?.join("; ") ?? "no createdWebhookId";
+    throw new Error(`Jira webhook registration entry malformed: ${errors}`);
+  }
+
+  const webhookId = first.createdWebhookId;
+  const expiresAt = new Date(Date.now() + THIRTY_DAYS_MS).toISOString();
+
+  // Persist via the read-modify-write helper so we don't clobber cloudId/siteUrl.
+  // updateJiraMetadata's id-keyed merge preserves any other webhookIds rows.
+  updateJiraMetadata({
+    webhookIds: [{ id: webhookId, expiresAt, jql: jqlFilter }],
+  });
+
+  console.log(
+    `[Jira webhook keepalive] Registered webhook id=${webhookId} jql='${jqlFilter}' (default expiry ${expiresAt})`,
+  );
+
+  return { webhookId, expiresAt, jql: jqlFilter };
+}
+
+/**
+ * Delete a dynamic webhook from Atlassian and remove it from `metadata.webhookIds`.
+ *
+ * Per Atlassian REST v3: `DELETE /rest/api/3/webhook` with body
+ * `{ webhookIds: [<int>, ...] }`. Atlassian silently ignores ids it doesn't
+ * recognize, so this is safe to call with stale local entries.
+ */
+export async function deleteJiraWebhook(webhookId: number): Promise<void> {
+  const response = await jiraFetch("/rest/api/3/webhook", {
+    method: "DELETE",
+    body: JSON.stringify({ webhookIds: [webhookId] }),
+  });
+
+  if (!response.ok && response.status !== 204) {
+    const errorText = await response.text().catch(() => "");
+    throw new Error(`Jira webhook delete failed (${response.status}): ${errorText}`);
+  }
+
+  // Remove the id from local metadata regardless of whether Atlassian had it.
+  const meta = getJiraMetadata();
+  const remaining = (meta.webhookIds ?? []).filter((entry) => entry.id !== webhookId);
+
+  // updateJiraMetadata's id-keyed merge can't drop entries (it merges by id).
+  // For removal we need the read-modify-write to overwrite the array. Bypass
+  // the merge by writing an empty `webhookIds` partial isn't supported either,
+  // so we manually compose the full list and call updateJiraMetadata once for
+  // each remaining entry — but that's quadratic. Instead: mutate via a
+  // single UPDATE statement bypassing the helper. Done in a transaction-safe
+  // way below.
+  await overwriteWebhookIds(remaining);
+
+  console.log(`[Jira webhook keepalive] Deleted webhook id=${webhookId}`);
+}
+
+/**
+ * Direct overwrite of the `webhookIds` array — needed when removing entries
+ * because `updateJiraMetadata`'s id-keyed merge cannot delete.
+ *
+ * Reads the current metadata, replaces just the `webhookIds` key, persists.
+ * Race-window with concurrent registrations is acceptable: deletions are
+ * rare admin actions, and the next register call will re-add anything we
+ * accidentally race-stomped.
+ */
+async function overwriteWebhookIds(
+  next: Array<{ id: number; expiresAt: string; jql: string }>,
+): Promise<void> {
+  const { getDb } = await import("../be/db");
+  const db = getDb();
+  const txn = db.transaction(() => {
+    const row = db.query("SELECT metadata FROM oauth_apps WHERE provider = 'jira'").get() as {
+      metadata: string | null;
+    } | null;
+
+    if (!row) {
+      throw new Error(
+        "[jira.webhook-lifecycle] oauth_apps row missing for provider='jira' — call initJira() first",
+      );
+    }
+
+    let current: Record<string, unknown> = {};
+    try {
+      const parsed = JSON.parse(row.metadata || "{}");
+      if (parsed && typeof parsed === "object") {
+        current = parsed as Record<string, unknown>;
+      }
+    } catch {
+      // fall through with empty
+    }
+
+    const merged = { ...current, webhookIds: next };
+    db.query(
+      "UPDATE oauth_apps SET metadata = ?, updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE provider = 'jira'",
+    ).run(JSON.stringify(merged));
+  });
+  txn();
+}
+
+/**
+ * Refresh known webhooks. Atlassian's `PUT /rest/api/3/webhook/refresh` takes
+ * `{ webhookIds: [...] }` and returns either:
+ *   - 200 + `{ expirationDate: "<ISO-8601>" }` (applies to ALL refreshed webhooks)
+ *   - 204 No Content (older API variant)
+ *
+ * Unrecognized ids are silently ignored. On a successful refresh that returns
+ * an `expirationDate`, we update every locally-known webhook to that expiry.
+ * On 204 (no body), we treat the call as best-effort and log a warning.
+ */
+export async function refreshJiraWebhooks(): Promise<void> {
+  const meta = getJiraMetadata();
+  const ids = (meta.webhookIds ?? []).map((entry) => entry.id);
+
+  if (ids.length === 0) {
+    console.log("[Jira webhook keepalive] No webhooks to refresh");
+    return;
+  }
+
+  console.log(`[Jira webhook keepalive] Refreshing ${ids.length} webhook(s): ${ids.join(", ")}`);
+
+  const response = await jiraFetch("/rest/api/3/webhook/refresh", {
+    method: "PUT",
+    body: JSON.stringify({ webhookIds: ids }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => "");
+    throw new Error(`Jira webhook refresh failed (${response.status}): ${errorText}`);
+  }
+
+  // 204 No Content → nothing to write back.
+  if (response.status === 204) {
+    console.warn(
+      "[Jira webhook keepalive] Refresh returned 204 (no expirationDate) — local expiries left as-is. Stale entries will surface on next tick.",
+    );
+    return;
+  }
+
+  let payload: { expirationDate?: string } | null = null;
+  try {
+    payload = (await response.json()) as { expirationDate?: string };
+  } catch {
+    payload = null;
+  }
+
+  const expirationDate = payload?.expirationDate;
+  if (!expirationDate || typeof expirationDate !== "string") {
+    console.warn(
+      "[Jira webhook keepalive] Refresh succeeded but response had no expirationDate — local expiries left as-is",
+    );
+    return;
+  }
+
+  // Apply the new expiry to all known entries (Atlassian docs: the new
+  // expiration applies to ALL refreshed webhooks).
+  const updated = (meta.webhookIds ?? []).map((entry) => ({
+    ...entry,
+    expiresAt: expirationDate,
+  }));
+  updateJiraMetadata({ webhookIds: updated });
+
+  console.log(
+    `[Jira webhook keepalive] Refreshed ${updated.length} webhook(s) → expiresAt=${expirationDate}`,
+  );
+}
+
+/**
+ * Run the keepalive check once: refresh webhooks expiring within 7 days.
+ *
+ * Errors are caught and reported (Slack-best-effort) so the timer survives
+ * transient network / token failures.
+ */
+async function runKeepalive(): Promise<void> {
+  try {
+    const meta = getJiraMetadata();
+    const entries = meta.webhookIds ?? [];
+    if (entries.length === 0) {
+      console.log("[Jira webhook keepalive] No webhooks registered, nothing to refresh");
+      return;
+    }
+
+    const now = Date.now();
+    const dueSoon = entries.filter((entry) => {
+      const expiry = Date.parse(entry.expiresAt);
+      if (!Number.isFinite(expiry)) return true; // malformed → refresh defensively
+      return expiry - now < SEVEN_DAYS_MS;
+    });
+
+    if (dueSoon.length === 0) {
+      console.log(
+        `[Jira webhook keepalive] All ${entries.length} webhook(s) have expiries >7 days out — skipping`,
+      );
+      return;
+    }
+
+    console.log(
+      `[Jira webhook keepalive] ${dueSoon.length}/${entries.length} webhook(s) expire within 7 days — refreshing all`,
+    );
+    await refreshJiraWebhooks();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[Jira webhook keepalive] Refresh failed: ${message}`);
+    await notifySlack(
+      `⚠️ *Jira webhook keepalive failed*\nError: ${message}\n\nWebhooks may expire — manual refresh via \`POST /api/trackers/jira/webhook-register\` may be required.`,
+    );
+  }
+}
+
+/**
+ * Start the recurring keepalive timer.
+ *
+ * Per plan errata I5: runs an immediate expiry check on first invocation
+ * (a stale webhook surfaces on boot, not after the first 12-hour tick), then
+ * every 12 hours.
+ */
+export function startJiraWebhookKeepalive(): void {
+  if (keepaliveInterval) {
+    console.log("[Jira webhook keepalive] Already running, skipping");
+    return;
+  }
+
+  console.log("[Jira webhook keepalive] Starting (12h interval, 7-day refresh threshold)");
+
+  // Immediate-on-boot check (after a short delay so server finishes startup
+  // and OAuth tokens are loaded). Mirrors src/oauth/keepalive.ts pattern.
+  setTimeout(() => {
+    runKeepalive();
+  }, 10_000);
+
+  keepaliveInterval = setInterval(() => {
+    runKeepalive();
+  }, TWELVE_HOURS_MS);
+}
+
+/**
+ * Stop the keepalive timer. Idempotent.
+ */
+export function stopJiraWebhookKeepalive(): void {
+  if (keepaliveInterval) {
+    clearInterval(keepaliveInterval);
+    keepaliveInterval = null;
+    console.log("[Jira webhook keepalive] Stopped");
+  }
+}

package/src/jira/webhook.ts

@@ -0,0 +1,159 @@
+/**
+ * Jira webhook receiver.
+ *
+ * Auth model: Atlassian does NOT HMAC-sign OAuth 3LO dynamic webhooks. Instead
+ * we embed a high-entropy random token (`JIRA_WEBHOOK_TOKEN`) in the path
+ * segment of the registered webhook URL and reject deliveries whose path
+ * token doesn't match (timing-safe compare). See plan errata I8.
+ *
+ * Dedup is DB-persisted (not a process-local Map) so it survives restarts:
+ * a synthetic deliveryId derived from `webhookEvent + timestamp + entity id +
+ * sha256(rawBody).slice(0,16)` is stored in `tracker_sync.lastDeliveryId`
+ * after each successful processing run.
+ */
+
+import { createHash, timingSafeEqual } from "node:crypto";
+import { hasTrackerDelivery, markTrackerDelivery } from "../be/db-queries/tracker";
+import { handleCommentEvent, handleIssueDeleteEvent, handleIssueEvent } from "./sync";
+
+/**
+ * Timing-safe compare of two URL-path tokens. Returns `false` for any of:
+ *   - missing / empty `pathToken` or `expected`
+ *   - length mismatch (we still call timingSafeEqual on padded buffers to
+ *     avoid leaking length via early-return timing — both arguments are
+ *     zero-padded to the longer length first)
+ *   - byte-for-byte mismatch
+ */
+export function verifyJiraWebhookToken(pathToken: string | undefined, expected: string): boolean {
+  if (!pathToken || !expected) return false;
+
+  const a = Buffer.from(pathToken, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  const len = Math.max(a.length, b.length);
+  const padA = Buffer.alloc(len);
+  const padB = Buffer.alloc(len);
+  a.copy(padA);
+  b.copy(padB);
+
+  // timingSafeEqual on equal-length padded buffers; the length-mismatch path
+  // is "real != real after padding" → returns false in constant time.
+  const equalBytes = timingSafeEqual(padA, padB);
+  return equalBytes && a.length === b.length;
+}
+
+/**
+ * Build a deliveryId from the raw body and parsed envelope. Stable across
+ * retries of the same delivery. The body-hash suffix kills same-millisecond
+ * collisions on different events.
+ */
+export function synthesizeDeliveryId(body: Record<string, unknown>, rawBody: string): string {
+  const event = String(body.webhookEvent ?? "");
+  const ts = String(body.timestamp ?? "");
+  const issue = body.issue as { id?: unknown } | undefined;
+  const comment = body.comment as { id?: unknown } | undefined;
+  const entityId = String(issue?.id ?? comment?.id ?? "_");
+  const hash = createHash("sha256").update(rawBody).digest("hex").slice(0, 16);
+  return `${event}:${ts}:${entityId}:${hash}`;
+}
+
+/** Public form so callers (and tests) can poke the same path. */
+export function isDuplicateDelivery(deliveryId: string): boolean {
+  return hasTrackerDelivery("jira", deliveryId);
+}
+
+/** Mark a delivery as processed for the given Jira entity. */
+export function markDelivery(externalId: string, deliveryId: string): void {
+  markTrackerDelivery("jira", "task", externalId, deliveryId);
+}
+
+// ─── Top-level dispatcher ──────────────────────────────────────────────────
+
+export type WebhookResult = {
+  status: number;
+  body: unknown;
+};
+
+/**
+ * Process a raw Jira webhook delivery. Returns the HTTP response shape; the
+ * caller owns writing it to the wire.
+ *
+ * Contract:
+ *   - 503 when `JIRA_WEBHOOK_TOKEN` is unset.
+ *   - 401 with empty body on token mismatch (no info leak).
+ *   - 200 + `{status: "accepted"|"duplicate"|"ignored"}` otherwise.
+ *
+ * Heavy work is fire-and-forget: we always return 200 once accepted to avoid
+ * Atlassian retrying on slow handlers.
+ */
+export async function handleJiraWebhook(
+  pathToken: string | undefined,
+  rawBody: string,
+): Promise<WebhookResult> {
+  const expected = process.env.JIRA_WEBHOOK_TOKEN;
+  if (!expected) {
+    return { status: 503, body: { error: "Jira webhook handler not configured" } };
+  }
+
+  if (!verifyJiraWebhookToken(pathToken, expected)) {
+    // Empty body — no leakage about valid-vs-missing.
+    return { status: 401, body: "" };
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(rawBody) as Record<string, unknown>;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[Jira Webhook] Malformed JSON body: ${msg}`);
+    // Atlassian-side bug shouldn't trigger retries — accept and drop.
+    return { status: 200, body: { status: "ignored", reason: "invalid-json" } };
+  }
+
+  const deliveryId = synthesizeDeliveryId(parsed, rawBody);
+  if (isDuplicateDelivery(deliveryId)) {
+    return { status: 200, body: { status: "duplicate" } };
+  }
+
+  const event = String(parsed.webhookEvent ?? "");
+
+  // Fire-and-forget heavy work; return 200 immediately.
+  void dispatchAndRecord(event, parsed, deliveryId).catch((err) => {
+    console.error("[Jira Webhook] Error processing event:", err, {
+      event,
+      deliveryId,
+    });
+  });
+
+  return { status: 200, body: { status: "accepted" } };
+}
+
+async function dispatchAndRecord(
+  event: string,
+  body: Record<string, unknown>,
+  deliveryId: string,
+): Promise<void> {
+  const issue = body.issue as { id?: unknown } | undefined;
+  const externalId = typeof issue?.id === "string" ? issue.id : null;
+
+  switch (event) {
+    case "jira:issue_updated":
+      await handleIssueEvent(body);
+      break;
+    case "comment_created":
+    case "comment_updated":
+      await handleCommentEvent(body);
+      break;
+    case "jira:issue_deleted":
+      await handleIssueDeleteEvent(body);
+      break;
+    default:
+      console.log(`[Jira Webhook] Ignoring unhandled event: ${event}`);
+      return;
+  }
+
+  // Best-effort: stamp the delivery on whichever sync row exists for this
+  // entity. No-op when the handler decided not to create one.
+  if (externalId) {
+    markDelivery(externalId, deliveryId);
+  }
+}

package/src/linear/app.ts

@@ -43,6 +43,23 @@ export function initLinear(): boolean {
 
   initLinearOutboundSync();
 
+  warnIfMcpBaseUrlLooksLikeAppUrl();
+
   console.log("[Linear] Integration initialized");
   return true;
 }
+
+/**
+ * Soft sanity check for `MCP_BASE_URL`. If it equals `APP_URL` (a common
+ * misconfig that surfaces a wrong-looking webhook URL in the dashboard),
+ * warn loudly so the operator can fix the env.
+ */
+function warnIfMcpBaseUrlLooksLikeAppUrl(): void {
+  const mcp = process.env.MCP_BASE_URL?.trim().replace(/\/+$/, "");
+  const app = process.env.APP_URL?.trim().replace(/\/+$/, "");
+  if (mcp && app && mcp === app) {
+    console.warn(
+      `[Linear] WARNING: MCP_BASE_URL (${mcp}) equals APP_URL — surfaced webhook URL points at the dashboard host, not the API. Configure Linear with this URL only if the dashboard host also serves /api/*.`,
+    );
+  }
+}

package/src/linear/oauth.ts

@@ -33,3 +33,27 @@ export async function handleLinearCallback(
   if (!config) throw new Error("Linear OAuth not configured");
   return exchangeCode(config, code, state);
 }
+
+/**
+ * Revoke an OAuth access token with Linear. Best-effort — caller should not
+ * abort the disconnect flow if this fails. Linear's revocation endpoint is
+ * `POST https://api.linear.app/oauth/revoke` with the access token in the
+ * Authorization header (per https://developers.linear.app/docs/oauth/authentication).
+ *
+ * Returns true on a 2xx response, false otherwise.
+ */
+export async function revokeLinearToken(accessToken: string): Promise<boolean> {
+  try {
+    const res = await fetch("https://api.linear.app/oauth/revoke", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    return res.ok;
+  } catch (err) {
+    console.warn(
+      "[Linear] Token revocation failed (best-effort):",
+      err instanceof Error ? err.message : err,
+    );
+    return false;
+  }
+}

package/src/oauth/wrapper.ts

@@ -13,6 +13,16 @@ export interface OAuthProviderConfig {
   scopes: string[];
   /** Extra query params appended to the authorization URL (e.g. { actor: "app" } for Linear) */
   extraParams?: Record<string, string>;
+  /**
+   * How to join `scopes` in the authorization URL.
+   *
+   * - Linear: `","` (its OAuth implementation requires comma-separated scopes).
+   * - Atlassian / RFC 6749 default: `" "` (space-separated).
+   *
+   * Defaults to `","` for backward compatibility with Linear, the only
+   * pre-existing consumer of this wrapper.
+   */
+  scopeSeparator?: string;
 }
 
 interface PendingState {
@@ -61,7 +71,7 @@ export async function buildAuthorizationUrl(
   url.searchParams.set("client_id", config.clientId);
   url.searchParams.set("redirect_uri", config.redirectUri);
   url.searchParams.set("response_type", "code");
-  url.searchParams.set("scope", config.scopes.join(","));
+  url.searchParams.set("scope", config.scopes.join(config.scopeSeparator ?? ","));
   url.searchParams.set("state", state);
   url.searchParams.set("code_challenge", codeChallenge);
   url.searchParams.set("code_challenge_method", "S256");

package/src/tasks/context-key.ts

@@ -12,6 +12,7 @@
  *   task:trackers:github:{owner}:{repo}:{issue|pr}:{number}
  *   task:trackers:gitlab:{projectId}:{mr|issue}:{iid}
  *   task:trackers:linear:{issueIdentifier}        (e.g. DES-42 — case preserved)
+ *   task:trackers:jira:{issueIdentifier}          (e.g. PROJ-123 — case preserved)
  *   task:schedule:{scheduleId}
  *   task:workflow:{workflowRunId}
  *
@@ -30,7 +31,7 @@ const SEPARATOR = ":";
 
 export type ContextKeyFamily = "slack" | "agentmail" | "trackers" | "schedule" | "workflow";
 
-export type TrackerProvider = "github" | "gitlab" | "linear";
+export type TrackerProvider = "github" | "gitlab" | "linear" | "jira";
 
 export type ParsedContextKey =
   | { family: "slack"; parts: { channelId: string; threadTs: string } }
@@ -50,6 +51,11 @@ export type ParsedContextKey =
       subFamily: "linear";
       parts: { issueIdentifier: string };
     }
+  | {
+      family: "trackers";
+      subFamily: "jira";
+      parts: { issueIdentifier: string };
+    }
   | { family: "schedule"; parts: { scheduleId: string } }
   | { family: "workflow"; parts: { workflowRunId: string } };
 
@@ -129,6 +135,18 @@ export function linearContextKey(input: { issueIdentifier: string }): string {
   return ["task", "trackers", "linear", issueIdentifier].join(SEPARATOR);
 }
 
+/**
+ * Build a Jira tracker context key. Plan Phase 1 names this `buildJiraContextKey`
+ * (positional `issueIdentifier`) rather than the `<provider>ContextKey({input})`
+ * shape used by older builders. New ingress sites should prefer this signature;
+ * the existing Linear/GitHub/GitLab builders are kept as-is to avoid touching
+ * unrelated call sites.
+ */
+export function buildJiraContextKey(issueIdentifier: string): string {
+  const id = assertSafePart(issueIdentifier, "issueIdentifier");
+  return ["task", "trackers", "jira", id].join(SEPARATOR);
+}
+
 export function scheduleContextKey(input: { scheduleId: string }): string {
   const scheduleId = assertSafePart(input.scheduleId, "scheduleId");
   return ["task", "schedule", scheduleId].join(SEPARATOR);
@@ -235,6 +253,16 @@ export function parseContextKey(key: string): ParsedContextKey {
           parts: { issueIdentifier: parts[3] as string },
         };
       }
+      if (subFamily === "jira") {
+        if (parts.length !== 4) {
+          throw new Error(`context-key: malformed jira key: ${JSON.stringify(key)}`);
+        }
+        return {
+          family: "trackers",
+          subFamily: "jira",
+          parts: { issueIdentifier: parts[3] as string },
+        };
+      }
       throw new Error(
         `context-key: unknown trackers sub-family "${subFamily}": ${JSON.stringify(key)}`,
       );