@desplega.ai/agent-swarm 2.4.4 → 2.5.0

package/src/be/seed-scripts/catalog/heartbeat-jev-gate.ts

@@ -13,11 +13,15 @@ export const argsSchema = z.object({
     .min(0)
     .max(1)
     .optional()
-    .describe("Quiet when Jev's p(needs action) is below this (default 0.5)"),
+    .describe(
+      "Quiet when the model's p(needs action) is below this (default: the provider's measured threshold, 0.5 for Jev, 0.2 for Clef)",
+    ),
   provider: z
-    .enum(["auto", "typesafe", "openrouter"])
+    .enum(["auto", "typesafe", "openrouter", "cloudflare"])
     .optional()
-    .describe("Jev host; auto prefers TypeSafe (default auto)"),
+    .describe(
+      "Decision host: typesafe or openrouter (Jev), cloudflare (Clef). auto tries them in that order (default auto)",
+    ),
   timeZone: z
     .string()
     .optional()
@@ -28,25 +32,56 @@ export const argsSchema = z.object({
     .min(1_000)
     .max(45_000)
     .optional()
-    .describe("Abandon the Jev call after this many ms (default 25000); the gate deadline is 60 s"),
+    .describe(
+      "Abandon the decision call after this many ms (default 25000); the gate deadline is 60 s",
+    ),
 });
 
 const KV_NAMESPACE = "heartbeat-jev-gate";
 const KV_KEY = "setup";
-// Measured per decision in the 2026-10-15 heartbeat replay (229 states).
-const COST_PER_DECISION = "$0.00004";
+// Jev's cost, measured per decision in the 2026-10-15 heartbeat replay (229 states).
+const JEV_COST_PER_DECISION = "$0.00004";
+// Clef replayed on the same 229 states and labels (2026-10-20): 0.2 is the highest
+// threshold that misses none of the 9 ticks where the Lead acted (57 quiet ticks;
+// Jev at 0.5 has 100). Above 0.21 Clef starts missing real asks.
+const CLEF_THRESHOLD = 0.2;
 
-// Jev is called through `ctx.swarm.systemOne_decide`: the API server reads the
-// key and sends the request, so no key ever enters this script's realm. The
+// The model is called through `ctx.swarm.systemOne_decide`: the API server reads
+// the key and sends the request, so no key ever enters this script's realm. The
 // server also refuses OpenRouter when the effective OPENROUTER_BASE_URL (stored
-// config or deployment env) points at a gateway.
+// config or deployment env) points at a gateway; `auto` then tries the next
+// usable provider, since this script cannot read the deployment env.
+//
+// `credentials` lists what must be set: every group needs one of its keys.
+// `threshold` is the default the provider's own replay measured (see `CLEF_THRESHOLD`).
 const PROVIDERS = {
-  typesafe: { keyName: "TYPESAFE_API_KEY", model: "jev-latest" },
-  openrouter: { keyName: "OPENROUTER_API_KEY", model: "~typesafe/jev-latest" },
+  typesafe: {
+    model: "jev-latest",
+    family: "jev",
+    threshold: 0.5,
+    credentials: [["TYPESAFE_API_KEY"]],
+    setup: "`TYPESAFE_API_KEY` (Jev on TypeSafe)",
+  },
+  openrouter: {
+    model: "~typesafe/jev-latest",
+    family: "jev",
+    threshold: 0.5,
+    credentials: [["OPENROUTER_API_KEY"]],
+    setup: "`OPENROUTER_API_KEY` (Jev on OpenRouter)",
+  },
+  cloudflare: {
+    model: "clef",
+    family: "clef",
+    threshold: CLEF_THRESHOLD,
+    credentials: [["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_KEY"], ["CLOUDFLARE_ACCOUNT_ID"]],
+    setup:
+      "`CLOUDFLARE_API_TOKEN` (or `CLOUDFLARE_API_KEY`) as a secret plus the `CLOUDFLARE_ACCOUNT_ID` config value (Clef on Cloudflare Workers AI)",
+  },
 } as const;
 type ProviderId = keyof typeof PROVIDERS;
+const AUTO_ORDER: ProviderId[] = ["typesafe", "openrouter", "cloudflare"];
 
-// Worded exactly as in the replay that set the 0.5 threshold; changing it voids that result.
+// Worded exactly as in the replays that set the thresholds; changing it voids those results.
 const QUESTIONS = {
   act: {
     type: "noul",
@@ -229,21 +264,25 @@ async function buildState(ctx: any, leadId: string, nowMs: number, timeZone: str
   };
 }
 
-function setupPrompt(keys: string[]) {
+function setupPrompt(candidates: ProviderId[]) {
+  const options = candidates.map((id) => `- ${PROVIDERS[id].setup}`);
   return {
-    title: "Heartbeat Jev gate: add a Jev credential or decline",
+    title: "Heartbeat gate: add a decision model credential or decline",
     detached: true,
     questions: [
       {
         id: "enable",
         type: "approval",
-        label: "Enable the Jev heartbeat gate?",
+        label: "Enable the heartbeat checklist gate?",
         description: [
-          "Before each recurring heartbeat checklist, the `heartbeat-jev-gate` script sends a short summary of swarm state (about 1,500 characters: new failures, due tracked items, task and agent counts) to Jev, a small decision model by TypeSafe, and asks whether the Lead needs to act. With `HEARTBEAT_CHECKLIST_GATE_MODE=enforce`, quiet ticks skip the Lead's checklist task.",
+          "Before each recurring heartbeat checklist, the `heartbeat-jev-gate` script sends a short summary of swarm state (about 1,500 characters: new failures, due tracked items, task and agent counts) to a small SystemOne decision model (Jev by TypeSafe, or Clef on Cloudflare Workers AI) and asks whether the Lead needs to act. With `HEARTBEAT_CHECKLIST_GATE_MODE=enforce`, quiet ticks skip the Lead's checklist task.",
           "",
-          `Cost: about ${COST_PER_DECISION} per decision, one decision per checklist tick.`,
+          `Cost: one decision per checklist tick, about ${JEV_COST_PER_DECISION} each with Jev.`,
           "",
-          `No Jev credential is configured. To enable, approve and add one of ${keys.map((k) => `\`${k}\``).join(" or ")} as a global secret on the Secrets page (Settings > Secrets). Do not paste the key here. The next tick picks it up.`,
+          "No credential for the gate is configured. To enable, approve and add one of these as a global value on the Secrets page (Settings > Secrets):",
+          ...options,
+          "",
+          "Do not paste a key here. The next tick picks it up.",
           "",
           "Reject to decline. The gate then stays inactive, with no further prompts, until a key is added.",
         ].join("\n"),
@@ -253,9 +292,10 @@ function setupPrompt(keys: string[]) {
 }
 
 /**
- * Heartbeat checklist gate backed by Jev: asks Jev whether a recurring checklist
- * tick needs the Lead and returns { quiet, reason, summary }. With no Jev
- * credential it asks a human once, then stays a no-op until a key is added.
+ * Heartbeat checklist gate backed by a SystemOne decision model (Jev or Clef):
+ * asks whether a recurring checklist tick needs the Lead and returns
+ * { quiet, reason, summary }. With no credential it asks a human once, then
+ * stays a no-op until a key is added.
  */
 export default async function heartbeatJevGate(args: any, ctx: any) {
   const parsed = argsSchema.safeParse(args ?? {});
@@ -276,25 +316,21 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
   };
 
   const cfgThreshold = Number.parseFloat(cfg("HEARTBEAT_JEV_GATE_THRESHOLD"));
-  const threshold =
-    a.threshold ?? (cfgThreshold >= 0 && cfgThreshold <= 1 ? cfgThreshold : 0.5);
   const providerPref = a.provider ?? (cfg("HEARTBEAT_JEV_GATE_PROVIDER").toLowerCase() || "auto");
   const timeZone = a.timeZone ?? (cfg("HEARTBEAT_JEV_GATE_TIMEZONE") || "UTC");
 
-  const usable: Record<ProviderId, boolean> = {
-    typesafe: cfg(PROVIDERS.typesafe.keyName) !== "",
-    openrouter: cfg(PROVIDERS.openrouter.keyName) !== "",
-  };
+  const usable = (id: ProviderId) =>
+    PROVIDERS[id].credentials.every((group) => group.some((key) => cfg(key) !== ""));
   const candidates: ProviderId[] =
-    providerPref === "typesafe"
-      ? ["typesafe"]
-      : providerPref === "openrouter"
-        ? ["openrouter"]
-        : ["typesafe", "openrouter"];
-  const provider = candidates.find((id) => usable[id]);
+    Object.hasOwn(PROVIDERS, providerPref) ? [providerPref as ProviderId] : AUTO_ORDER;
+  const usableCandidates = candidates.filter(usable);
 
-  if (!provider) {
-    const keys = candidates.map((id) => PROVIDERS[id].keyName);
+  if (usableCandidates.length === 0) {
+    const keys = candidates.map((id) =>
+      PROVIDERS[id].credentials
+        .map((group) => (group.length > 1 ? `(${group.join(" or ")})` : group[0]))
+        .join(" + "),
+    );
     const inactive = (state: string, extra: Record<string, unknown> = {}) => ({
       quiet: false,
       reason: `jev-gate inactive: ${state}`.slice(0, 300),
@@ -305,7 +341,7 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
     let setup: SetupState | null = typeof stored === "string" ? JSON.parse(stored) : (stored ?? null);
 
     if (!setup) {
-      const prompt = setupPrompt(keys);
+      const prompt = setupPrompt(candidates);
       if (dryRun) {
         const state = await buildState(ctx, leadId, Date.now(), timeZone);
         return inactive("no credential, would ask a human", { prompt, state });
@@ -349,35 +385,51 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
     return inactive(why, { setup });
   }
 
-  const target = PROVIDERS[provider];
   const state = await buildState(ctx, leadId, Date.now(), timeZone);
 
-  // The server enforces the time budget. No retries, as in the replay.
-  const res: any = await ctx.swarm.systemOne_decide({
-    provider,
-    model: target.model,
-    state,
-    questions: QUESTIONS,
-    timeoutMs: a.jevTimeoutMs ?? 25_000,
-    maxRetries: 0,
-  });
-  const body: any = res?.data ?? res;
-  if (res?.success === false || body?.success === false) {
-    throw new Error(`jev ${provider}: ${String(body?.message ?? body?.error ?? `HTTP ${res?.status}`).slice(0, 250)}`);
+  // The server enforces the time budget. No retries, as in the replay. A provider
+  // this deployment refuses (OpenRouter behind a gateway) sends nothing, so the
+  // next usable one is tried; only an explicit choice or the last one throws.
+  let provider = usableCandidates[0] as ProviderId;
+  let body: any;
+  const skipped: string[] = [];
+  for (const [i, id] of usableCandidates.entries()) {
+    provider = id;
+    const res: any = await ctx.swarm.systemOne_decide({
+      provider: id,
+      model: PROVIDERS[id].model,
+      state,
+      questions: QUESTIONS,
+      timeoutMs: a.jevTimeoutMs ?? 25_000,
+      maxRetries: 0,
+    });
+    body = res?.data ?? res;
+    if (res?.success !== false && body?.success !== false) break;
+    const why = String(body?.message ?? body?.error ?? `HTTP ${res?.status}`).slice(0, 250);
+    if (body?.providerUnavailable === true && i < usableCandidates.length - 1) {
+      skipped.push(`${id}: ${why}`);
+      continue;
+    }
+    throw new Error(`${PROVIDERS[id].family} ${id}: ${why}`);
   }
+  const target = PROVIDERS[provider];
+  // A configured threshold applies to every provider; unset, each uses its measured one.
+  const threshold =
+    a.threshold ?? (cfgThreshold >= 0 && cfgThreshold <= 1 ? cfgThreshold : target.threshold);
   const p = body?.answers?.act?.noul;
   if (typeof p !== "number" || !Number.isFinite(p)) {
-    throw new Error(`jev ${provider}: response has no numeric answers.act.noul`);
+    throw new Error(`${target.family} ${provider}: response has no numeric answers.act.noul`);
   }
 
   const pText = p.toFixed(3);
   const quiet = p < threshold;
   const verdict: Record<string, unknown> = {
     quiet,
-    reason: `jev p(needs action)=${pText} ${quiet ? "<" : ">="} ${threshold} via ${provider}`,
+    reason: `${target.family} p(needs action)=${pText} ${quiet ? "<" : ">="} ${threshold} via ${provider}`,
   };
   if (!quiet) {
-    const lines = [`Jev p(needs action) = ${pText} (threshold ${threshold}, ${provider}).`];
+    const model = target.family === "jev" ? "Jev" : "Clef";
+    const lines = [`${model} p(needs action) = ${pText} (threshold ${threshold}, ${provider}).`];
     const failures = state.new_failures_since_previous_heartbeat;
     const tracked = state.tracked_items_mentioning_today_or_past_delete_date;
     if (Array.isArray(failures)) {
@@ -387,9 +439,9 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
       lines.push("", "Tracked items due today or past their DELETE date:", ...tracked.map((t) => `- ${t.replace(/^[-*] /, "")}`));
     }
     if (!Array.isArray(failures) && !Array.isArray(tracked)) {
-      lines.push("", "No new failures or due tracked items; Jev flagged the overall state.");
+      lines.push("", `No new failures or due tracked items; ${model} flagged the overall state.`);
     }
     verdict.summary = lines.join("\n").slice(0, 4000);
   }
-  return dryRun ? { ...verdict, dryRun: true, provider, p, threshold, state } : verdict;
+  return dryRun ? { ...verdict, dryRun: true, provider, skipped, p, threshold, state } : verdict;
 }

package/src/be/seed-scripts/index.ts

@@ -116,9 +116,9 @@ export const SEED_SCRIPTS: SeedScript[] = [
   {
     name: "heartbeat-jev-gate",
     description:
-      "Heartbeat checklist gate backed by Jev (TypeSafe or OpenRouter decisions API): scores a compact swarm state and returns {quiet, reason, summary} for HEARTBEAT_CHECKLIST_GATE_SCRIPT.",
+      "Heartbeat checklist gate backed by a SystemOne decision model (Jev on TypeSafe or OpenRouter, Clef on Cloudflare Workers AI): scores a compact swarm state and returns {quiet, reason, summary} for HEARTBEAT_CHECKLIST_GATE_SCRIPT.",
     intent:
-      "Skip quiet Lead heartbeat checklist ticks with a cheap Jev decision; with no Jev credential it asks a human once, then stays a no-op until a key is added.",
+      "Skip quiet Lead heartbeat checklist ticks with a cheap Jev or Clef decision; with no credential it asks a human once, then stays a no-op until a key is added.",
     source: asText(heartbeatJevGateSrc),
   },
   {

package/src/be/skill-sync.ts

@@ -10,6 +10,7 @@
  */
 
 import { homedir } from "node:os";
+import type { SkillFile, SkillWithInstallInfo } from "../types";
 import {
   type SkillFsEntry,
   type SkillHarnessTarget,
@@ -71,8 +72,7 @@ export interface SkillsSignature {
  * uninstall, toggle, or skill-update mutates at least one of them. Output is
  * deterministic and contains no timestamps beyond per-row mutation fields.
  */
-export async function computeAgentSkillsSignature(agentId: string): Promise<SkillsSignature> {
-  const skills = await getAgentSkills(agentId);
+export function computeSkillsSignature(skills: readonly SkillWithInstallInfo[]): SkillsSignature {
   const sorted = [...skills].sort((a, b) => a.id.localeCompare(b.id));
   const canonical = JSON.stringify(
     sorted.map((s) => [
@@ -89,3 +89,44 @@ export async function computeAgentSkillsSignature(agentId: string): Promise<Skil
   const hash = new Bun.CryptoHasher("sha256").update(canonical).digest("hex");
   return { hash, count: sorted.length };
 }
+
+/**
+ * Fetch the agent's skills and sign them.
+ *
+ * Callers that already hold the rows (the bundle endpoint) must use
+ * `computeSkillsSignature` on those exact rows instead of calling this: a
+ * second read can observe a newer edit and pair a fresh hash with stale
+ * payload bytes, which makes later signature probes skip the refresh forever.
+ */
+export async function computeAgentSkillsSignature(agentId: string): Promise<SkillsSignature> {
+  return computeSkillsSignature(await getAgentSkills(agentId));
+}
+
+export interface SkillsBundle {
+  skills: (SkillWithInstallInfo & { files: SkillFile[] })[];
+  total: number;
+  signature: string;
+}
+
+/**
+ * Build the worker boot payload: every installed skill plus its bundled files,
+ * signed over the rows this same call returned.
+ *
+ * The readers are injected so the ordering the fix depends on is testable: the
+ * signature is taken before the first `readFiles`, so an edit that lands while
+ * the files are being read cannot pair stale bytes with a newer hash.
+ */
+export async function buildSkillsBundle(
+  readSkills: () => Promise<SkillWithInstallInfo[]>,
+  readFiles: (skillId: string) => Promise<SkillFile[]>,
+): Promise<SkillsBundle> {
+  const skills = await readSkills();
+  const signature = computeSkillsSignature(skills).hash;
+  const entries = await Promise.all(
+    skills.map(async (skill) => ({
+      ...skill,
+      files: skill.isComplex ? await readFiles(skill.id) : [],
+    })),
+  );
+  return { skills: entries, total: entries.length, signature };
+}

package/src/be/swarm-config-guard.ts

@@ -68,7 +68,11 @@ const RESERVED_KEYS = new Set([
 // the agent-fs bootstrap admin key would let a compromised worker administer the
 // shared org. The API materializes these into its own process.env at boot via
 // getInjectableGlobalConfigs, so no HTTP consumer legitimately needs them.
-const API_ONLY_CONFIG_KEYS = new Set(["API_AGENT_FS_API_KEY", "SLACK_SIGNING_SECRET"]);
+const API_ONLY_CONFIG_KEYS = new Set([
+  "API_AGENT_FS_API_KEY",
+  "SLACK_SIGNING_SECRET",
+  "TRANSCRIPTION_API_KEY",
+]);
 
 export function isApiOnlyConfigKey(key: string): boolean {
   return API_ONLY_CONFIG_KEYS.has(key);
@@ -160,6 +164,20 @@ export const APPS_JSON_COLUMN_MAX_BYTES_BOUNDS = { min: 1_024, max: 16_777_216 }
  */
 export const CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS_BOUNDS = { min: 1, max: 216 } as const;
 
+/**
+ * Decision hosts `SYSTEM_ONE_DEFAULT_PROVIDER` may name: `SYSTEM_ONE_PROVIDER_IDS`
+ * in `src/workflows/executors/system-one-providers.ts`, listed here because that
+ * module's credential readers would pull the LLM stack into every `db.ts` import.
+ * A test keeps the two lists equal.
+ */
+export const SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS = [
+  "typesafe",
+  "openrouter",
+  "laya",
+  "openai",
+  "cloudflare",
+] as const;
+
 /** Build `{ KEY: validator }` entries accepting only boolean literals. */
 function booleanValidators(keys: string[]): Record<string, ConfigValidator> {
   const message = (key: string) =>
@@ -399,6 +417,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   },
   ...enumValidator("CLAUDE_TRANSPORT", ["cli", "sdk"]),
   ...enumValidator("SCRIPT_EXECUTOR", ["native", "quickjs"]),
+  ...enumValidator("TRANSCRIPTION_PROVIDER", ["openai", "elevenlabs", "groq"]),
   SCRIPT_QUICKJS_POOL_SIZE: validateQuickJSPoolSize,
   ...booleanValidators(["SCRIPT_EGRESS_ALLOW_PRIVATE"]),
   SCRIPT_EGRESS_ALLOWLIST: (value) =>
@@ -407,6 +426,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   // model's weekly window (Fable/Opus/Sonnet). fallback: legacy random pick.
   ...enumValidator("MODEL_WINDOW_EXHAUSTED_POLICY", ["fail", "fallback"]),
   ...enumValidator("HEARTBEAT_CHECKLIST_GATE_MODE", ["shadow", "enforce"]),
+  ...enumValidator("SYSTEM_ONE_DEFAULT_PROVIDER", [...SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS]),
   // Codex credits-exhausted cooldown (ms). Permissive on range here (positive
   // integer) — the worker clamps to [5m, 7d] via resolveCodexCreditsExhaustedCooldownMs.
   CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS: (value) => {
@@ -479,6 +499,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "GITHUB_DISABLE",
     "GITLAB_DISABLE",
     "AZURE_DEVOPS_DISABLE",
+    "BITBUCKET_DISABLE",
     "LINEAR_DISABLE",
     "JIRA_DISABLE",
     "AGENTMAIL_DISABLE",
@@ -582,6 +603,9 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   // default in thread-buffer.ts; above 10 minutes a
   // reply waits longer than any operator expects.
   ...boundedIntegerValidators(["CHAT_SDK_BUFFER_MS"], 1, 600_000),
+  // Minutes a Chat SDK thread keeps its owner after the owner's task ends.
+  // 0 keeps it only while the task is open; a day is the longest useful window.
+  ...boundedIntegerValidators(["CHAT_SDK_OWNER_WINDOW_MIN"], 0, 1440),
   // Below ~100 tokens the preamble can't fit a useful summary; above 20000
   // (~80k chars) it risks the SIGTERM-143 context-saturation failure mode
   // the cap exists to prevent (see context-preamble.ts).

package/src/be/task-attachment-store.ts

@@ -68,3 +68,33 @@ export async function recordTaskAttachmentUpload(
     throw error;
   }
 }
+
+// Resolve against the row's ACTUAL stored key + its own org/drive, rather than
+// reconstructing `tasks/<taskId>/<name>`. Attachments written to agent-fs via the
+// CLI live at arbitrary paths (`misc/…`, `smoke/…`); reconstruction mis-resolves
+// them, which previously caused downloads to 404 and deletes to orphan the real
+// file. New uploads have no stored key yet at scope-build time and keep the
+// forward-looking layout.
+export function scopeFromAttachment(attachment: TaskAttachment): FileScope {
+  const storedKey = attachment.providerKey ?? attachment.path ?? "";
+  return {
+    taskId: attachment.taskId,
+    name: attachment.name,
+    key: storedKey.trim() ? storedKey : undefined,
+    orgId: attachment.orgId,
+    driveId: attachment.driveId,
+  };
+}
+
+// Which file-storage provider (if any) actually holds this attachment's bytes.
+// Only agent-fs objects and local-fs uploads are provider-backed; `shared-fs`
+// worker-volume pointers, `url`, and `page` attachments have no provider object,
+// so they must never be fetched or deleted through a provider (doing so would
+// mis-resolve and, on delete, orphan the real target). Note local-fs uploads are
+// recorded with kind "shared-fs" but an explicit local-fs providerId, so key off
+// both signals rather than kind alone.
+export function backingProviderId(attachment: TaskAttachment): string | null {
+  if (attachment.kind === "agent-fs") return attachment.providerId ?? "agent-fs";
+  if (attachment.providerId === "local-fs") return "local-fs";
+  return null;
+}

package/src/bitbucket/api.ts

@@ -0,0 +1,81 @@
+/**
+ * Bitbucket Cloud REST interactions — resolving the bot identity behind the
+ * token and posting pull request comments. Uses raw fetch, no SDK.
+ */
+
+import { scrubSecrets } from "../utils/secret-scrubber";
+import { getBitbucketToken } from "./auth";
+
+export const BITBUCKET_API = "https://api.bitbucket.org/2.0";
+
+function headers(): Record<string, string> {
+  const token = getBitbucketToken();
+  if (!token) throw new Error("[Bitbucket] No API token configured");
+  return {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+}
+
+let cachedBotAccountId: string | null = null;
+
+/**
+ * Atlassian `account_id` of the bot. A picker @mention is stored as
+ * `@{<account_id>}` in the comment's raw content, so this is what mention
+ * detection matches. Uses BITBUCKET_BOT_ACCOUNT_ID when set, otherwise the
+ * user that owns the token (`GET /2.0/user`), cached. Returns null when
+ * neither is available; callers then fall back to plain-text `@name` matching.
+ */
+export async function resolveBitbucketBotAccountId(): Promise<string | null> {
+  const fromEnv = process.env.BITBUCKET_BOT_ACCOUNT_ID?.trim();
+  if (fromEnv) return fromEnv;
+  if (cachedBotAccountId) return cachedBotAccountId;
+  if (!getBitbucketToken()) return null;
+  try {
+    // Redirects are refused so the token never follows a response to another host.
+    const resp = await fetch(`${BITBUCKET_API}/user`, { headers: headers(), redirect: "error" });
+    if (!resp.ok) {
+      console.error(`[Bitbucket] GET /user returned ${resp.status}`);
+      return null;
+    }
+    const data = (await resp.json()) as { account_id?: string };
+    cachedBotAccountId = data.account_id?.trim() || null;
+    return cachedBotAccountId;
+  } catch (err) {
+    console.error(`[Bitbucket] Failed to resolve bot identity: ${scrubSecrets(String(err))}`);
+    return null;
+  }
+}
+
+/** Reset the cached bot identity (tests, config reloads). */
+export function resetBitbucketBotCache(): void {
+  cachedBotAccountId = null;
+}
+
+/** Post a comment on a pull request. `fullName` is `<workspace>/<repo_slug>`. */
+export async function postBitbucketPullRequestComment(
+  fullName: string,
+  pullRequestId: number,
+  raw: string,
+): Promise<void> {
+  const [workspace, repoSlug] = fullName.split("/");
+  if (!workspace || !repoSlug) throw new Error(`[Bitbucket] Invalid repository: ${fullName}`);
+  const url =
+    `${BITBUCKET_API}/repositories/${encodeURIComponent(workspace)}/` +
+    `${encodeURIComponent(repoSlug)}/pullrequests/${pullRequestId}/comments`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: headers(),
+    redirect: "error",
+    body: JSON.stringify({ content: { raw } }),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(
+      scrubSecrets(
+        `[Bitbucket] Comment on ${fullName}#${pullRequestId} failed: ${resp.status} ${text}`,
+      ),
+    );
+  }
+}

package/src/bitbucket/auth.ts

@@ -0,0 +1,64 @@
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import { verifyHmacSignature } from "../workflows/triggers";
+
+/**
+ * Bitbucket Cloud Authentication & Webhook Verification
+ *
+ * Webhooks are signed with the webhook's secret: `X-Hub-Signature` carries
+ * `sha256=<hex HMAC-SHA256 of the raw body>`, checked against
+ * BITBUCKET_WEBHOOK_SECRET. API calls send BITBUCKET_TOKEN (an Atlassian API
+ * token or a workspace access token) as a Bearer token.
+ */
+
+let initialized = false;
+let webhookSecret: string | null = null;
+let apiToken: string | null = null;
+
+export function isBitbucketEnabled(): boolean {
+  return !!process.env.BITBUCKET_WEBHOOK_SECRET && !isEnvFlagEnabled("BITBUCKET_DISABLE", false);
+}
+
+export function initBitbucket(): void {
+  if (initialized) return;
+  if (!isBitbucketEnabled()) {
+    console.log("[Bitbucket] Integration disabled (BITBUCKET_WEBHOOK_SECRET not set)");
+    return;
+  }
+
+  webhookSecret = process.env.BITBUCKET_WEBHOOK_SECRET!;
+  apiToken = process.env.BITBUCKET_TOKEN ?? null;
+  initialized = true;
+
+  console.log(`[Bitbucket] Integration initialized (API token: ${apiToken ? "set" : "not set"})`);
+}
+
+/**
+ * Verify a Bitbucket webhook delivery from its raw body and `X-Hub-Signature`
+ * header. Only the `sha256=<hex>` form Bitbucket sends is accepted.
+ */
+export function verifyBitbucketWebhook(rawBody: string, signatureHeader: string | undefined) {
+  if (!webhookSecret) return false;
+  if (!signatureHeader?.startsWith("sha256=")) return false;
+  return verifyHmacSignature(webhookSecret, rawBody, signatureHeader);
+}
+
+/** Get the Bitbucket token for API calls. */
+export function getBitbucketToken(): string | null {
+  return apiToken;
+}
+
+/**
+ * Bot name for plain-text `@name` mentions. Read on every call: a stored
+ * swarm_config value reaches process.env after this module loads, and again
+ * on each config reload.
+ */
+export function getBitbucketBotName(): string {
+  return process.env.BITBUCKET_BOT_NAME || "agent-swarm-bot";
+}
+
+/** Reset state for testing and config reloads. */
+export function resetBitbucket(): void {
+  initialized = false;
+  webhookSecret = null;
+  apiToken = null;
+}