@desplega.ai/agent-swarm 2.4.4 → 2.5.0

package/src/utils/page-session.ts

@@ -246,23 +246,83 @@ export function parseCookieHeader(
 }
 
 /**
- * One-shot helper: pull `page_session` out of a request's `Cookie` header and
- * verify it. Returns the parsed payload on success, `null` on any failure
- * (no cookie, malformed, bad signature, expired, etc.).
- *
- * Shared by `/@swarm/api/*` (`src/http/page-proxy.ts`) and the authed `/p/:id`
- * branch (`src/http/pages-public.ts`) so both call sites converge on the same
- * verification semantics.
+ * The single shared cookie name used before sessions became per-page. Every
+ * launch overwrote it, so only the newest page in a browser had a session.
+ * Still read for back-compat, but only for the page its payload names.
+ */
+export const LEGACY_PAGE_SESSION_COOKIE = "page_session";
+
+/** Page ids are 32 hex chars today; anything outside the cookie-name-safe set is refused. */
+const COOKIE_SAFE_PAGE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function isCookieSafePageId(pageId: string): boolean {
+  return COOKIE_SAFE_PAGE_ID.test(pageId);
+}
+
+/** Per-page cookie name, so sessions for different pages coexist in one browser. */
+export function pageSessionCookieName(pageId: string): string {
+  return `${LEGACY_PAGE_SESSION_COOKIE}_${pageId}`;
+}
+
+export interface VerifiedPageSession {
+  /** The raw signed token, forwarded upstream by the page proxy. */
+  token: string;
+  payload: PageSessionPayload;
+}
+
+type CookieRequest = { headers: { cookie?: string | string[] | undefined } };
+
+async function verifyNamedCookie(
+  req: CookieRequest,
+  name: string,
+): Promise<VerifiedPageSession | null> {
+  const token = parseCookieHeader(req.headers.cookie, name);
+  const payload = await verifyPageSession(token);
+  return payload && token ? { token, payload } : null;
+}
+
+/**
+ * Find and verify the session for `pageId`: `page_session_<pageId>` first,
+ * then the legacy `page_session`. A cookie whose signed payload names a
+ * different page is ignored, so the result always satisfies
+ * `payload.pageId === pageId`. Returns `null` on any failure (no cookie,
+ * malformed, bad signature, expired, wrong page).
+ */
+export async function extractPageSession(
+  req: CookieRequest,
+  pageId: string,
+): Promise<VerifiedPageSession | null> {
+  if (!isCookieSafePageId(pageId)) return null;
+  for (const name of [pageSessionCookieName(pageId), LEGACY_PAGE_SESSION_COOKIE]) {
+    const session = await verifyNamedCookie(req, name);
+    if (session?.payload.pageId === pageId) return session;
+  }
+  return null;
+}
+
+/**
+ * Verify the legacy `page_session` cookie for whatever page it names. Only for
+ * callers that send no page id (clients predating per-page cookies).
+ */
+export async function extractLegacyPageSession(
+  req: CookieRequest,
+): Promise<VerifiedPageSession | null> {
+  return verifyNamedCookie(req, LEGACY_PAGE_SESSION_COOKIE);
+}
+
+/**
+ * Payload-only form of `extractPageSession`. Shared by the `/p/:id` handler
+ * (`src/http/pages-public.ts`) and the realtime upgrade
+ * (`src/realtime/transport.ts`) so they converge on the same semantics.
  *
  * Accepts an object with a `headers.cookie` field — duck-typed to keep this
  * helper test-friendly without dragging `node:http` types into the utility.
  */
-export async function extractAndVerifyCookie(req: {
-  headers: { cookie?: string | string[] | undefined };
-}): Promise<PageSessionPayload | null> {
-  const token = parseCookieHeader(req.headers.cookie, "page_session");
-  if (!token) return null;
-  return verifyPageSession(token);
+export async function extractAndVerifyCookie(
+  req: CookieRequest,
+  pageId: string,
+): Promise<PageSessionPayload | null> {
+  return (await extractPageSession(req, pageId))?.payload ?? null;
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -284,6 +344,10 @@ const PAGE_SESSION_TTL_SECONDS = 3600;
  * - `dev=true` → `SameSite=Lax` without `Secure` (works on http://localhost).
  * - `dev=false` → `SameSite=None; Secure` (cross-site iframe embedding in prod).
  *
+ * The cookie is named `page_session_<pageId>`, so launching page B leaves
+ * page A's session intact. Responses should go through `pageSessionSetCookies`,
+ * which also bounds how many of these a browser keeps.
+ *
  * The caller is responsible for setting `Set-Cookie` on the response — this
  * helper only builds the string. TTL is 1 hour; renewed on every issuance.
  */
@@ -299,13 +363,12 @@ export async function issuePageSessionCookie(
     ...(opts.name ? { name: opts.name } : {}),
     ...(opts.op ? { op: true as const } : {}),
   });
-  const attrs = [
-    `page_session=${token}`,
-    "HttpOnly",
-    "Path=/",
-    `Max-Age=${PAGE_SESSION_TTL_SECONDS}`,
-  ];
-  if (opts.dev) {
+  return buildCookie(pageSessionCookieName(pageId), token, PAGE_SESSION_TTL_SECONDS, opts.dev);
+}
+
+function buildCookie(name: string, value: string, maxAge: number, dev: boolean): string {
+  const attrs = [`${name}=${value}`, "HttpOnly", "Path=/", `Max-Age=${maxAge}`];
+  if (dev) {
     attrs.push("SameSite=Lax");
   } else {
     attrs.push("SameSite=None");
@@ -313,3 +376,53 @@ export async function issuePageSessionCookie(
   }
   return attrs.join("; ");
 }
+
+/**
+ * Most per-page session cookies one browser keeps, counting the one being
+ * issued. Each is ~220 bytes on the wire, and `Path=/` sends all of them on
+ * every request to this host, so an unbounded jar grows past the server's
+ * 16 KB header limit (431 on every route, `/health` included) after ~75
+ * launches within the hour. 20 keeps the jar near 4.5 KB.
+ */
+export const MAX_PAGE_SESSION_COOKIES = 20;
+
+const PAGE_SESSION_COOKIE_RE = new RegExp(
+  `(?:^|;\\s*)(${LEGACY_PAGE_SESSION_COOKIE}_[A-Za-z0-9_-]{1,64})=([^;]*)`,
+  "g",
+);
+
+/**
+ * `Set-Cookie` values for a launch of `pageId`: the new session, plus an
+ * expiring cookie for every other per-page session in the request's jar that
+ * is invalid or expired, or falls outside the `MAX_PAGE_SESSION_COOKIES - 1`
+ * newest. The browser then holds at most `MAX_PAGE_SESSION_COOKIES` of them.
+ * An evicted page's open tab loses its session, the same as after expiry.
+ */
+export async function pageSessionSetCookies(
+  req: CookieRequest,
+  pageId: string,
+  opts: { dev: boolean; uid?: string; name?: string; op?: true },
+): Promise<string[]> {
+  const issued = await issuePageSessionCookie(pageId, opts);
+  const header = Array.isArray(req.headers.cookie)
+    ? req.headers.cookie.join("; ")
+    : (req.headers.cookie ?? "");
+  const keep: { name: string; exp: number; order: number }[] = [];
+  const evict = new Set<string>();
+  const seen = new Set([pageSessionCookieName(pageId)]);
+  for (const [, name, token] of header.matchAll(PAGE_SESSION_COOKIE_RE)) {
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    const payload = await verifyPageSession(token);
+    if (payload && name === pageSessionCookieName(payload.pageId)) {
+      keep.push({ name, exp: payload.exp, order: keep.length });
+    } else {
+      evict.add(name);
+    }
+  }
+  // `exp` has one-second granularity. Browsers list older cookies first, so a
+  // later position breaks ties toward the more recent launch.
+  keep.sort((a, b) => b.exp - a.exp || b.order - a.order);
+  for (const { name } of keep.slice(MAX_PAGE_SESSION_COOKIES - 1)) evict.add(name);
+  return [issued, ...[...evict].map((name) => buildCookie(name, "", 0, opts.dev))];
+}

package/src/utils/secret-scrubber.ts

@@ -53,6 +53,10 @@ const SENSITIVE_KEY_EXACT = new Set<string>([
   "AZURE_DEVOPS_TOKEN",
   // Worker-side copy of AZURE_DEVOPS_TOKEN read by the az azure-devops extension
   "AZURE_DEVOPS_EXT_PAT",
+  // The `_TOKEN` / `_SECRET` suffixes already match these, so listing them
+  // does not change redaction and does not bump SCRUBBER_RULES_VERSION.
+  "BITBUCKET_TOKEN",
+  "BITBUCKET_WEBHOOK_SECRET",
   "CLAUDE_CODE_OAUTH_TOKEN",
   "ANTHROPIC_API_KEY",
   "OPENAI_API_KEY",

package/src/utils/skills-refresh.ts

@@ -77,26 +77,56 @@ export async function refreshSkillsIfChanged(
     isEnabled: boolean;
     isActive: boolean;
   };
+  type BundledFile = { path: string; content: string; isBinary: boolean };
   let skillRows: SkillRow[] = [];
+  // Present when the bundle call succeeded: every complex skill's files arrive
+  // in the same response, so Step 3 never fans out per file.
+  let bundledFiles: Map<string, BundledFile[]> | null = null;
   let newHash: string | null = null;
   let listFetchOk = false;
+
+  // Preferred path: one request for the skills and all of their bundled files.
+  // A 4xx from an older server (no bundle endpoint yet) falls through to the
+  // legacy list + per-file path below.
   try {
-    const skillsResp = await fetch(`${apiUrl}/api/agents/${agentId}/skills`, {
+    const bundleResp = await fetch(`${apiUrl}/api/agents/${agentId}/skills/bundle`, {
       headers: authHeaders,
     });
-    if (skillsResp.ok) {
-      const skillsData = (await skillsResp.json()) as {
-        skills: SkillRow[];
+    if (bundleResp.ok) {
+      const bundle = (await bundleResp.json()) as {
+        skills: (SkillRow & { files?: BundledFile[] })[];
         signature?: string;
       };
-      skillRows = skillsData.skills;
-      if (typeof skillsData.signature === "string") {
-        newHash = skillsData.signature;
+      skillRows = bundle.skills;
+      bundledFiles = new Map(bundle.skills.map((skill) => [skill.id, skill.files ?? []]));
+      if (typeof bundle.signature === "string") {
+        newHash = bundle.signature;
       }
       listFetchOk = true;
     }
   } catch {
-    // Transient network / parse error — bail out without touching the local FS
+    // Transient network / parse error — the legacy path below gets a chance.
+  }
+
+  if (!listFetchOk) {
+    try {
+      const skillsResp = await fetch(`${apiUrl}/api/agents/${agentId}/skills`, {
+        headers: authHeaders,
+      });
+      if (skillsResp.ok) {
+        const skillsData = (await skillsResp.json()) as {
+          skills: SkillRow[];
+          signature?: string;
+        };
+        skillRows = skillsData.skills;
+        if (typeof skillsData.signature === "string") {
+          newHash = skillsData.signature;
+        }
+        listFetchOk = true;
+      }
+    } catch {
+      // Transient network / parse error — bail out without touching the local FS
+    }
   }
 
   // Guard: a failed list fetch must not proceed to writeSkillsToFilesystem.
@@ -125,45 +155,55 @@ export async function refreshSkillsIfChanged(
       const files: { path: string; content: string; isBinary: boolean }[] = [];
 
       if (skill.isComplex) {
-        // Fetch manifest to know which files exist + which are binary
-        try {
-          const manifestResp = await fetch(`${apiUrl}/api/skills/${skill.id}/files`, {
-            headers: authHeaders,
-          });
-          if (manifestResp.ok) {
-            const manifestData = (await manifestResp.json()) as {
-              files: { path: string; isBinary: boolean }[];
-            };
-
-            // Fetch content for each non-binary file (N+1 — acceptable for v1)
-            for (const manifestEntry of manifestData.files) {
-              if (manifestEntry.isBinary) {
-                files.push({ path: manifestEntry.path, content: "", isBinary: true });
-                continue;
-              }
-              try {
-                const encodedPath = manifestEntry.path.split("/").map(encodeURIComponent).join("/");
-                const fileResp = await fetch(
-                  `${apiUrl}/api/skills/${skill.id}/files/${encodedPath}`,
-                  { headers: authHeaders },
-                );
-                if (fileResp.ok) {
-                  const fileData = (await fileResp.json()) as {
-                    file: { path: string; content: string; isBinary: boolean };
-                  };
-                  files.push({
-                    path: fileData.file.path,
-                    content: fileData.file.content,
-                    isBinary: fileData.file.isBinary,
-                  });
+        const bundled = bundledFiles?.get(skill.id);
+        if (bundled) {
+          // Bundle path: every file (including binaries) arrived with the
+          // skill list, so there is nothing left to fetch.
+          files.push(...bundled);
+        } else {
+          // Legacy server: fetch manifest to know which files exist + which are binary
+          try {
+            const manifestResp = await fetch(`${apiUrl}/api/skills/${skill.id}/files`, {
+              headers: authHeaders,
+            });
+            if (manifestResp.ok) {
+              const manifestData = (await manifestResp.json()) as {
+                files: { path: string; isBinary: boolean }[];
+              };
+
+              // Fetch content for each non-binary file (N+1 — acceptable for v1)
+              for (const manifestEntry of manifestData.files) {
+                if (manifestEntry.isBinary) {
+                  files.push({ path: manifestEntry.path, content: "", isBinary: true });
+                  continue;
+                }
+                try {
+                  const encodedPath = manifestEntry.path
+                    .split("/")
+                    .map(encodeURIComponent)
+                    .join("/");
+                  const fileResp = await fetch(
+                    `${apiUrl}/api/skills/${skill.id}/files/${encodedPath}`,
+                    { headers: authHeaders },
+                  );
+                  if (fileResp.ok) {
+                    const fileData = (await fileResp.json()) as {
+                      file: { path: string; content: string; isBinary: boolean };
+                    };
+                    files.push({
+                      path: fileData.file.path,
+                      content: fileData.file.content,
+                      isBinary: fileData.file.isBinary,
+                    });
+                  }
+                } catch {
+                  // Non-fatal — skip this file
                 }
-              } catch {
-                // Non-fatal — skip this file
               }
             }
+          } catch {
+            // Non-fatal — treat as no files (will skip complex skill per writer logic)
           }
-        } catch {
-          // Non-fatal — treat as no files (will skip complex skill per writer logic)
         }
       }
 

package/src/utils/transcription.ts

@@ -0,0 +1,246 @@
+/**
+ * Speech-to-text for inbound audio. `TRANSCRIPTION_PROVIDER` picks the request
+ * shape:
+ *
+ * - `openai`: `POST <base>/audio/transcriptions`, `Authorization: Bearer`, form
+ *   field `model`. OpenAI Whisper and self-hosted whisper servers speak this
+ *   shape.
+ * - `groq`: the `openai` shape against Groq's OpenAI-compatible endpoint.
+ * - `elevenlabs`: `POST <base>/speech-to-text`, `xi-api-key` header, form
+ *   field `model_id`.
+ *
+ * The key: an explicit `TRANSCRIPTION_API_KEY` wins, with `TRANSCRIPTION_PROVIDER`
+ * (default `openai`). Without it, transcription reuses a provider key the
+ * swarm already has: the pinned provider's key when `TRANSCRIPTION_PROVIDER` is
+ * set, else the first of `ELEVENLABS_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`.
+ * Off when none is set.
+ *
+ * `TRANSCRIPTION_MODEL` overrides the provider's default model.
+ * `TRANSCRIPTION_BASE_URL` overrides its base URL for an explicit key only: an
+ * auto-detected key always goes to its provider's own endpoint. Deepgram and AssemblyAI use other request shapes and are not
+ * supported. Read at call time, so a config reload applies without a restart.
+ */
+import { createValueScrubber, scrubSecrets } from "./secret-scrubber";
+
+const TRANSCRIPTION_TIMEOUT_MS = 60_000;
+
+/** The config key that switches transcription on explicitly. */
+export const TRANSCRIPTION_API_KEY_ENV = "TRANSCRIPTION_API_KEY";
+
+type ProviderSpec = {
+  /** The provider's own key, reused when `TRANSCRIPTION_API_KEY` is unset. */
+  keyEnv: string;
+  defaultBaseUrl: string;
+  defaultModel: string;
+  path: string;
+  modelField: string;
+  authHeaders: (apiKey: string) => Record<string, string>;
+};
+
+const openAIShape = {
+  path: "/audio/transcriptions",
+  modelField: "model",
+  authHeaders: (apiKey: string) => ({ authorization: `Bearer ${apiKey}` }),
+};
+
+const PROVIDERS = {
+  openai: {
+    keyEnv: "OPENAI_API_KEY",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "whisper-1",
+    ...openAIShape,
+  },
+  groq: {
+    keyEnv: "GROQ_API_KEY",
+    defaultBaseUrl: "https://api.groq.com/openai/v1",
+    defaultModel: "whisper-large-v3-turbo",
+    ...openAIShape,
+  },
+  elevenlabs: {
+    keyEnv: "ELEVENLABS_API_KEY",
+    defaultBaseUrl: "https://api.elevenlabs.io/v1",
+    defaultModel: "scribe_v2",
+    path: "/speech-to-text",
+    modelField: "model_id",
+    authHeaders: (apiKey) => ({ "xi-api-key": apiKey }),
+  },
+} satisfies Record<string, ProviderSpec>;
+
+export type TranscriptionProvider = keyof typeof PROVIDERS;
+
+/** Order in which an existing provider key is picked when nothing is pinned. */
+const AUTO_DETECT_ORDER: TranscriptionProvider[] = ["elevenlabs", "openai", "groq"];
+
+/** Every env key the provider and key resolution reads. */
+export const TRANSCRIPTION_ENV_KEYS = [
+  TRANSCRIPTION_API_KEY_ENV,
+  "TRANSCRIPTION_PROVIDER",
+  "TRANSCRIPTION_BASE_URL",
+  "TRANSCRIPTION_MODEL",
+  ...AUTO_DETECT_ORDER.map((name) => PROVIDERS[name].keyEnv),
+];
+
+export class TranscriptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TranscriptionError";
+  }
+}
+
+/** The provider and key a transcription call uses. */
+export type TranscriptionConfig = {
+  provider: string;
+  apiKey: string;
+  /** The env key the API key came from. */
+  keyEnv: string;
+  /** `explicit`: `TRANSCRIPTION_API_KEY`. `auto`: a provider key the swarm already had. */
+  source: "explicit" | "auto";
+};
+
+function envValue(key: string): string | undefined {
+  return process.env[key]?.trim() || undefined;
+}
+
+/** Resolve provider and key, or null when no key is set. Unsupported provider names pass through. */
+export function resolveTranscriptionConfig(): TranscriptionConfig | null {
+  const pinned = envValue("TRANSCRIPTION_PROVIDER")?.toLowerCase();
+  const explicitKey = envValue(TRANSCRIPTION_API_KEY_ENV);
+  if (explicitKey) {
+    return {
+      provider: pinned ?? "openai",
+      apiKey: explicitKey,
+      keyEnv: TRANSCRIPTION_API_KEY_ENV,
+      source: "explicit",
+    };
+  }
+  // A pinned provider only uses its own key, never another provider's.
+  const candidates = pinned
+    ? AUTO_DETECT_ORDER.filter((name) => name === pinned)
+    : AUTO_DETECT_ORDER;
+  for (const name of candidates) {
+    const { keyEnv } = PROVIDERS[name];
+    const apiKey = envValue(keyEnv);
+    if (apiKey) return { provider: name, apiKey, keyEnv, source: "auto" };
+  }
+  return null;
+}
+
+export function isTranscriptionConfigured(): boolean {
+  return resolveTranscriptionConfig() !== null;
+}
+
+function providerSpec(name: string): ProviderSpec {
+  if (!Object.hasOwn(PROVIDERS, name)) {
+    throw new TranscriptionError(
+      `TRANSCRIPTION_PROVIDER "${name}" is not supported (use ${Object.keys(PROVIDERS).join(", ")})`,
+    );
+  }
+  return PROVIDERS[name as TranscriptionProvider];
+}
+
+/** OpenAI puts the reason in `error.message`; ElevenLabs in `detail.message` or `detail`. */
+function errorDetail(payload: Record<string, unknown> | null, status: number): string {
+  const error = payload?.error as { message?: unknown } | undefined;
+  if (typeof error?.message === "string") return error.message;
+  const detail = payload?.detail as { message?: unknown } | string | undefined;
+  if (typeof detail === "string") return detail;
+  if (typeof detail?.message === "string") return detail.message;
+  return `HTTP ${status}`;
+}
+
+/** Transcribe one audio file. Throws `TranscriptionError` when unconfigured or when the call fails. */
+export async function transcribeAudio(input: {
+  data: Blob;
+  filename: string;
+  mimeType?: string;
+}): Promise<string> {
+  const config = resolveTranscriptionConfig();
+  if (!config) throw new TranscriptionError("no transcription provider key is set");
+  const { apiKey } = config;
+  const provider = providerSpec(config.provider);
+  // An auto-detected key only goes to its own provider: a base URL set in
+  // config must not receive a key that was stored for another purpose.
+  const baseUrlOverride =
+    config.source === "explicit" ? process.env.TRANSCRIPTION_BASE_URL?.trim() : undefined;
+  const baseUrl = (baseUrlOverride || provider.defaultBaseUrl).replace(/\/+$/, "");
+  // scrubSecrets skips known values under 12 chars, and a self-hosted key can
+  // be shorter, so the submitted key is scrubbed by value from every error.
+  const keyScrubber = createValueScrubber([{ value: apiKey, name: config.keyEnv }]);
+  const scrub = (text: string) => scrubSecrets(keyScrubber.text(text));
+  const form = new FormData();
+  const type = input.mimeType ?? input.data.type;
+  form.append("file", type ? new Blob([input.data], { type }) : input.data, input.filename);
+  form.append(
+    provider.modelField,
+    process.env.TRANSCRIPTION_MODEL?.trim() || provider.defaultModel,
+  );
+
+  let response: Response;
+  try {
+    response = await fetch(`${baseUrl}${provider.path}`, {
+      method: "POST",
+      headers: provider.authHeaders(apiKey),
+      body: form,
+      signal: AbortSignal.timeout(TRANSCRIPTION_TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      throw new TranscriptionError(`no answer within ${TRANSCRIPTION_TIMEOUT_MS / 1000} s`);
+    }
+    throw new TranscriptionError(scrub(error instanceof Error ? error.message : String(error)));
+  }
+  const payload = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+  if (!response.ok || typeof payload?.text !== "string") {
+    throw new TranscriptionError(scrub(errorDetail(payload, response.status)));
+  }
+  return payload.text.trim();
+}
+
+/** The task-text note for an audio file when no provider is configured. */
+export const NOT_TRANSCRIBED_NOTE = `(not transcribed: no transcription provider configured, set ${TRANSCRIPTION_API_KEY_ENV} or one of ${AUTO_DETECT_ORDER.map((name) => PROVIDERS[name].keyEnv).join(", ")})`;
+
+const AUDIO_EXTENSIONS: Record<string, string> = {
+  "audio/ogg": "ogg",
+  "audio/opus": "ogg",
+  "audio/mpeg": "mp3",
+  "audio/mp4": "m4a",
+  "audio/x-m4a": "m4a",
+  "audio/wav": "wav",
+  "audio/x-wav": "wav",
+  "audio/webm": "webm",
+};
+
+/** One audio file to transcribe. `key` names its note in the returned map. */
+export type AudioFile = { key: string; name: string; data: Blob; mimeType?: string };
+
+/**
+ * Transcribe audio files into task-text notes, one per file: `[Transcript of
+ * <name>]` and the text, `(transcription failed: <reason>)`, or (when no
+ * provider is configured) `NOT_TRANSCRIBED_NOTE`. Never throws, so a failed
+ * call never blocks the task it belongs to. `logPrefix` tags the warning.
+ */
+export async function transcribeAudioNotes(
+  files: AudioFile[],
+  logPrefix: string,
+): Promise<Map<string, string>> {
+  const notes = new Map<string, string>();
+  if (files.length === 0) return notes;
+  if (!isTranscriptionConfigured()) {
+    for (const file of files) notes.set(file.key, NOT_TRANSCRIBED_NOTE);
+    return notes;
+  }
+  for (const file of files) {
+    // Voice notes can carry no file name; the endpoint reads the format from the extension.
+    const extension = AUDIO_EXTENSIONS[file.mimeType ?? ""] ?? "ogg";
+    const filename = /\.\w+$/.test(file.name) ? file.name : `${file.name}.${extension}`;
+    try {
+      const text = await transcribeAudio({ data: file.data, filename, mimeType: file.mimeType });
+      notes.set(file.key, `[Transcript of ${file.name}]\n${text || "(no speech recognized)"}`);
+    } catch (error) {
+      const reason = scrubSecrets(error instanceof Error ? error.message : String(error));
+      console.warn(`${logPrefix} could not transcribe file ${file.key}: ${reason}`);
+      notes.set(file.key, `(transcription failed: ${reason})`);
+    }
+  }
+  return notes;
+}

package/src/vcs/bitbucket.ts

@@ -0,0 +1,58 @@
+/**
+ * Bitbucket Cloud URL helpers. Pure functions, safe on both the API server and
+ * the worker (no DB imports). Bitbucket Data Center is out of scope.
+ */
+
+/**
+ * True when the URL's host is bitbucket.org. Only the host counts, so a
+ * `bitbucket.org` path segment on another host (`gitlab.com/bitbucket.org/x`)
+ * is not Bitbucket.
+ */
+export function isBitbucketUrl(url: string): boolean {
+  const trimmed = url.trim();
+  // SCP-style SSH: user@host:path
+  const scp = trimmed.match(/^[^@/\s:]+@([^:/\s]+):/);
+  if (scp) return (scp[1] as string).toLowerCase() === "bitbucket.org";
+  try {
+    return new URL(trimmed).hostname.toLowerCase() === "bitbucket.org";
+  } catch {
+    // Scheme-less `bitbucket.org/ws/repo`
+    return /^bitbucket\.org(\/|$)/i.test(trimmed);
+  }
+}
+
+/**
+ * Split a Bitbucket Cloud remote into its workspace and repository slug.
+ * Accepts the HTTPS forms (with or without a `user@` prefix, trailing `/` or
+ * `.git`) and the SSH forms (`git@bitbucket.org:ws/repo.git`,
+ * `ssh://git@bitbucket.org/ws/repo.git`). Returns null otherwise.
+ */
+export function parseBitbucketRepoUrl(url: string): { workspace: string; repoSlug: string } | null {
+  const trimmed = url.trim();
+  if (!isBitbucketUrl(trimmed)) return null;
+
+  // SCP-style SSH: git@bitbucket.org:{workspace}/{repo}.git
+  const scp = trimmed.match(/^[^@/\s]+@bitbucket\.org:([^/]+)\/([^/]+?)(?:\.git)?\/?$/i);
+  if (scp) return { workspace: scp[1] as string, repoSlug: scp[2] as string };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (parsed.hostname.toLowerCase() !== "bitbucket.org") return null;
+  const parts = parsed.pathname
+    .replace(/\.git\/?$/, "")
+    .split("/")
+    .filter(Boolean);
+  const [workspace, repoSlug] = parts;
+  if (!workspace || !repoSlug) return null;
+  return { workspace: decodeURIComponent(workspace), repoSlug: decodeURIComponent(repoSlug) };
+}
+
+/** `workspace/repo_slug` for a Bitbucket Cloud remote, or null. */
+export function bitbucketFullName(url: string): string | null {
+  const parsed = parseBitbucketRepoUrl(url);
+  return parsed ? `${parsed.workspace}/${parsed.repoSlug}` : null;
+}

package/src/vcs/index.ts

@@ -3,6 +3,7 @@
  */
 
 import { isAzureDevOpsUrl } from "./azure-devops";
+import { isBitbucketUrl } from "./bitbucket";
 import type { VcsProvider } from "./types";
 
 export type { VcsProvider } from "./types";
@@ -13,6 +14,7 @@ export type { VcsProvider } from "./types";
  */
 export function detectVcsProvider(url: string): VcsProvider | null {
   if (isAzureDevOpsUrl(url)) return "azure-devops";
+  if (isBitbucketUrl(url)) return "bitbucket";
   if (url.includes("gitlab.com") || url.includes("gitlab.")) return "gitlab";
   if (url.includes("github.com") || /^[\w.-]+\/[\w.-]+$/.test(url)) return "github";
   return null;