@desplega.ai/agent-swarm 2.4.5 → 2.5.0

package/src/bitbucket/templates.ts

@@ -0,0 +1,134 @@
+/**
+ * Bitbucket Cloud event prompt template definitions.
+ *
+ * Each template is registered at module load time via registerTemplate().
+ * Handlers import this module for the side-effect of registration.
+ *
+ * Template text uses {{variable}} syntax. The resolver interpolates variables
+ * and expands {{@template[id]}} references before returning the final text.
+ */
+
+import { registerTemplate } from "../prompts/registry";
+
+// ============================================================================
+// Common building blocks (Bitbucket-specific)
+// ============================================================================
+
+registerTemplate({
+  eventType: "common.delegation_instruction.bitbucket",
+  header: "",
+  defaultBody:
+    "\n\n**Delegation instruction:** As the lead agent, analyze this and decide whether to handle it yourself or delegate to a worker agent. Use `send-task` to delegate with clear instructions.",
+  variables: [],
+  category: "common",
+});
+
+// There is no Bitbucket CLI in the worker image, so the recipes are curl calls
+// against the REST API with the worker's BITBUCKET_TOKEN.
+registerTemplate({
+  eventType: "common.command_suggestions.bitbucket_pr",
+  header: "",
+  defaultBody:
+    'Workers have `git` authenticated for bitbucket.org and `BITBUCKET_TOKEN` in env; there is no Bitbucket CLI, so use curl against `https://api.bitbucket.org/2.0/repositories/{{repo}}` with `-H "Authorization: Bearer $BITBUCKET_TOKEN"`. Inspect the PR with `GET .../pullrequests/{{pr_id}}` and its diff with `GET .../pullrequests/{{pr_id}}/diff`. Reply with `POST .../pullrequests/{{pr_id}}/comments` and JSON body `{"content":{"raw":"<reply>"}}`. Find a PR by branch with `GET .../pullrequests?q=source.branch.name="<branch>"`. Open a PR with `POST .../pullrequests` and JSON body `{"title":"<title>","source":{"branch":{"name":"<branch>"}},"destination":{"branch":{"name":"<base>"}}}`.',
+  variables: [
+    { name: "repo", description: "Repository full name (<workspace>/<repo_slug>)" },
+    { name: "pr_id", description: "Pull request ID" },
+  ],
+  category: "common",
+});
+
+const SHARED_VARIABLES = [
+  { name: "pr_id", description: "Pull request ID" },
+  { name: "pr_title", description: "Pull request title" },
+  { name: "repo", description: "Repository full name (<workspace>/<repo_slug>)" },
+  { name: "pr_url", description: "Pull request web URL" },
+];
+
+const PR_BRANCH_VARIABLES = [
+  { name: "source_branch", description: "Source branch name" },
+  { name: "target_branch", description: "Target branch name" },
+  { name: "context_section", description: "Context section with description or empty string" },
+];
+
+// ============================================================================
+// Pull request events
+// ============================================================================
+
+registerTemplate({
+  eventType: "bitbucket.pull_request.opened",
+  header: "[Bitbucket PR #{{pr_id}}] {{pr_title}}",
+  defaultBody: `Repo: {{repo}}
+Author: {{username}}
+Branch: {{source_branch}} → {{target_branch}}
+URL: {{pr_url}}
+
+{{context_section}}{{@template[common.command_suggestions.bitbucket_pr]}}{{@template[common.delegation_instruction.bitbucket]}}`,
+  variables: [
+    ...SHARED_VARIABLES,
+    {
+      name: "username",
+      description:
+        "Author identity — resolved canonical name (e.g. 'Luis (bitbucket:557058:…)') or the UNKNOWN sentinel",
+    },
+    ...PR_BRANCH_VARIABLES,
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "bitbucket.pull_request.review_requested",
+  header: "[Bitbucket PR #{{pr_id}}] Review requested: {{pr_title}}",
+  defaultBody: `Repo: {{repo}}
+Author: {{username}}
+Branch: {{source_branch}} → {{target_branch}}
+URL: {{pr_url}}
+
+You were added as a reviewer on this pull request.
+
+{{context_section}}{{@template[common.command_suggestions.bitbucket_pr]}}{{@template[common.delegation_instruction.bitbucket]}}`,
+  variables: [
+    ...SHARED_VARIABLES,
+    {
+      name: "username",
+      description:
+        "Author identity — resolved canonical name (e.g. 'Luis (bitbucket:557058:…)') or the UNKNOWN sentinel",
+    },
+    ...PR_BRANCH_VARIABLES,
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Pull request comment events
+// ============================================================================
+
+registerTemplate({
+  eventType: "bitbucket.comment.mentioned",
+  header: "[Bitbucket Comment on PR #{{pr_id}}] {{username}} mentioned bot",
+  defaultBody: `Repo: {{repo}}
+PR: {{pr_title}}
+URL: {{pr_url}}
+{{location_section}}
+Comment:
+{{context}}{{existing_task_note}}
+
+{{@template[common.command_suggestions.bitbucket_pr]}}{{@template[common.delegation_instruction.bitbucket]}}`,
+  variables: [
+    ...SHARED_VARIABLES,
+    {
+      name: "username",
+      description:
+        "Comment author identity — resolved canonical name (e.g. 'Luis (bitbucket:557058:…)') or the UNKNOWN sentinel",
+    },
+    {
+      name: "location_section",
+      description: "`File: <path>:<line>` line for inline comments, or empty string",
+    },
+    { name: "context", description: "Extracted mention context from comment" },
+    {
+      name: "existing_task_note",
+      description: "Note about existing active task, or empty string",
+    },
+  ],
+  category: "event",
+});

package/src/bitbucket/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Bitbucket Cloud webhook payload types (subsets of the documented event
+ * payloads; only the fields the handlers read).
+ * https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/
+ */
+
+export interface BitbucketAccount {
+  type?: string;
+  /** Atlassian account id, e.g. `557058:<uuid>`. Absent for some app/team actors. */
+  account_id?: string;
+  /** Bitbucket user UUID, wrapped in braces: `{…}`. */
+  uuid?: string;
+  display_name?: string;
+  nickname?: string;
+}
+
+export interface BitbucketRepository {
+  /** Repository UUID, wrapped in braces: `{…}`. Stable across renames. */
+  uuid: string;
+  /** `<workspace>/<repo_slug>` */
+  full_name: string;
+  name?: string;
+  links?: { html?: { href: string } };
+}
+
+export interface BitbucketBranchRef {
+  branch?: { name: string };
+  commit?: { hash: string };
+  repository?: BitbucketRepository;
+}
+
+export interface BitbucketPullRequest {
+  id: number;
+  title: string;
+  description?: string | null;
+  state?: "OPEN" | "MERGED" | "DECLINED" | "SUPERSEDED";
+  author?: BitbucketAccount;
+  source?: BitbucketBranchRef;
+  destination?: BitbucketBranchRef;
+  reviewers?: BitbucketAccount[];
+  links?: { html?: { href: string } };
+}
+
+export interface BitbucketComment {
+  id: number;
+  content: { raw: string; markup?: string; html?: string };
+  user?: BitbucketAccount;
+  inline?: { path: string; from?: number | null; to?: number | null } | null;
+  parent?: { id: number } | null;
+  links?: { html?: { href: string } };
+}
+
+/** `pullrequest:created`, `pullrequest:fulfilled`, `pullrequest:rejected` */
+export interface PullRequestEvent {
+  actor: BitbucketAccount;
+  pullrequest: BitbucketPullRequest;
+  repository: BitbucketRepository;
+}
+
+/** `pullrequest:comment_created` */
+export interface PullRequestCommentEvent extends PullRequestEvent {
+  comment: BitbucketComment;
+}
+
+export type BitbucketWebhookEvent = PullRequestEvent | PullRequestCommentEvent;

package/src/commands/runner.ts

@@ -108,6 +108,7 @@ import {
   isAzureDevOpsUrl,
   parseAzureDevOpsRepoUrl,
 } from "../vcs/azure-devops.ts";
+import { bitbucketFullName, isBitbucketUrl, parseBitbucketRepoUrl } from "../vcs/bitbucket.ts";
 import { detectVcsProvider, type VcsProvider } from "../vcs/index.ts";
 import { validateJsonSchema } from "../workflows/json-schema-validator.ts";
 import { buildAttachmentsSection } from "./attachments-section.ts";
@@ -311,6 +312,7 @@ const CONTINUATION_TASK_TYPES = new Set([
   "gitlab-comment",
   "gitlab-ci",
   "azure-devops-comment",
+  "bitbucket-comment",
 ]);
 
 /**
@@ -2946,11 +2948,51 @@ const vcsDetectedTasks = new Set<string>();
 const vcsCheckTimestamps = new Map<string, number>();
 const VCS_CHECK_INTERVAL = 60_000; // 60 seconds
 
+/**
+ * Find the open Bitbucket Cloud pull request whose source branch is `branch`.
+ * There is no Bitbucket CLI in the worker image, so this calls the REST API
+ * with `BITBUCKET_TOKEN` as a Bearer token. Returns null when the token is
+ * unset, the remote is not a Bitbucket Cloud repo, the API answers non-2xx,
+ * no PR matches, or the request fails. Never throws.
+ */
+export async function findBitbucketOpenPullRequest(
+  remoteUrl: string,
+  branch: string,
+  opts: { token?: string; fetchImpl?: typeof fetch } = {},
+): Promise<{ number: number; url: string } | null> {
+  const token = opts.token ?? process.env.BITBUCKET_TOKEN;
+  if (!token) return null;
+  const repo = parseBitbucketRepoUrl(remoteUrl);
+  if (!repo) return null;
+  const query = `source.branch.name="${branch.replace(/["\\]/g, "\\$&")}" AND state="OPEN"`;
+  const url =
+    `https://api.bitbucket.org/2.0/repositories/${encodeURIComponent(repo.workspace)}` +
+    `/${encodeURIComponent(repo.repoSlug)}/pullrequests?q=${encodeURIComponent(query)}&pagelen=1`;
+  try {
+    const res = await (opts.fetchImpl ?? fetch)(url, {
+      headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as {
+      values?: Array<{ id?: unknown; links?: { html?: { href?: unknown } } }>;
+    };
+    const pr = body.values?.[0];
+    const href = pr?.links?.html?.href;
+    if (typeof pr?.id !== "number" || pr.id <= 0 || typeof href !== "string" || !href) {
+      return null;
+    }
+    return { number: pr.id, url: href };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Detect if the task's working directory has an open PR for the current branch.
  * If found, report VCS info to the API so webhook events can link back to this task.
  */
-async function detectVcsForTask(
+export async function detectVcsForTask(
   apiUrl: string,
   apiKey: string,
   taskId: string,
@@ -2974,6 +3016,7 @@ async function detectVcsForTask(
     let vcsProvider: VcsProvider;
     let prJson: string;
     let azureRepo: string | null = null;
+    let bitbucketRepo: string | null = null;
 
     if (isAzureDevOpsUrl(remoteUrl)) {
       const parsed = parseAzureDevOpsRepoUrl(remoteUrl);
@@ -2991,6 +3034,14 @@ async function detectVcsForTask(
           url: `${azureRepo}/pullrequest/${pr.pullRequestId}`,
         })),
       );
+    } else if (isBitbucketUrl(remoteUrl)) {
+      // Checked before the loose "github" substring match below, so a
+      // Bitbucket repo with "github" in its slug is not sent to `gh`.
+      bitbucketRepo = bitbucketFullName(remoteUrl);
+      if (!bitbucketRepo) return;
+      vcsProvider = "bitbucket";
+      const pr = await findBitbucketOpenPullRequest(remoteUrl, branch);
+      prJson = JSON.stringify(pr ? [pr] : []);
     } else if (remoteUrl.includes("github.com") || remoteUrl.includes("github")) {
       vcsProvider = "github";
       prJson = (
@@ -3017,9 +3068,10 @@ async function detectVcsForTask(
     if (!vcsNumber || !vcsUrl) return;
 
     // 6. Extract repo from remote URL (Azure Repos keep the canonical clone URL,
-    // matching the vcsRepo their webhook tasks carry)
+    // matching the vcsRepo their webhook tasks carry; Bitbucket uses the
+    // `workspace/repo_slug` full name its webhook tasks carry)
     const repoMatch = remoteUrl.match(/[:/]([^/]+\/[^/.]+?)(?:\.git)?$/);
-    const vcsRepo = azureRepo ?? repoMatch?.[1];
+    const vcsRepo = azureRepo ?? bitbucketRepo ?? repoMatch?.[1];
     if (!vcsRepo) return;
 
     // 7. Report to API

package/src/e2b/env.ts

@@ -29,6 +29,7 @@ export const DEFAULT_E2B_FORWARD_KEYS = [
   "GITLAB_TOKEN",
   "AZURE_DEVOPS_TOKEN",
   "AZURE_DEVOPS_ORG_URL",
+  "BITBUCKET_TOKEN",
   "LINEAR_API_KEY",
   "SLACK_BOT_TOKEN",
   "SLACK_SIGNING_SECRET",

package/src/extensions/contract-types.generated.ts

@@ -1,4 +1,4 @@
 // Generated by scripts/bundle-extension-types.ts. Do not edit.
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: Type declarations contain literal template placeholders.
 export const EXTENSION_TYPE_DEFINITIONS =
-  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRequester?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    poolWakeAt?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    resolvedEffort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    resolvedProfile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | "amp"\n      | "cursor"\n      | "grok"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  /** A Chat SDK message after its thread buffer flushed, before routing. */\n  export interface ChatRouteEvent {\n    /** Adapter name, such as `telegram` or `slack`. */\n    adapter: string;\n    channelId: string;\n    /** The Chat SDK thread id, prefixed with the adapter name. */\n    threadId: string;\n    /** The first buffered sender. */\n    userId: string;\n    userName?: string;\n    /** The buffered messages, joined. */\n    text: string;\n    /** True for an @mention and for a reply to one of the bot\'s messages. */\n    botMentioned: boolean;\n    isDirectMessage: boolean;\n    /** Platform chat type, such as Telegram `private`, `group`, `supergroup` or `channel`. */\n    chatType?: string;\n    /** Set for a Telegram supergroup with topics. */\n    isForum?: boolean;\n    /** A buffered message replies to one of the bot\'s own messages. */\n    replyToBot: boolean;\n    /** Set when earlier swarm tasks exist in this thread. */\n    threadContext?: {\n      adapter: string;\n      threadId: string;\n    };\n  }\n  export interface ChatRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        }\n      | {\n          kind: "workflow";\n          workflowId: string;\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  /** A Chat SDK message the swarm received or sent. */\n  export interface ChatMessageEvent {\n    adapter: string;\n    channelId: string;\n    threadId: string;\n    /** The sender, for an inbound message. */\n    userId?: string;\n    text: string;\n    direction: "inbound" | "outbound";\n    taskId?: string;\n    messageId?: string;\n  }\n  /**\n   * A person answered an approval request. Fires for workflow and standalone\n   * requests. Timeouts and cancellations do not emit it today.\n   */\n  export interface ApprovalResolvedEvent {\n    requestId: string;\n    status: "approved" | "rejected" | "timeout" | "cancelled";\n    responses: Record<string, unknown> | null;\n    /** Set when a workflow human-in-the-loop step asked. Absent for a standalone request. */\n    workflowRunId?: string;\n    workflowRunStepId?: string;\n    /** The task whose agent asked, for a standalone request. */\n    sourceTaskId?: string;\n  }\n  /** A task was refused because a daily spend budget is used up. */\n  export interface TaskBudgetRefusedEvent extends TaskEvent {\n    /** The agent the task was refused for. */\n    agentId: string;\n    /** Which budget refused it. The matching spend and budget fields are set. */\n    cause: "agent" | "global" | "user";\n    agentSpendUsd?: number;\n    agentBudgetUsd?: number;\n    globalSpendUsd?: number;\n    globalBudgetUsd?: number;\n    userSpendUsd?: number;\n    userBudgetUsd?: number;\n    /** ISO 8601 time the daily budget resets. */\n    resetAt: string;\n  }\n  /** An inbound AgentMail message. */\n  export interface EmailReceivedEvent {\n    inboxId: string;\n    /** The From header as sent. */\n    from: string;\n    subject: string;\n    /** The text body, or the HTML when there is no text, cut to 500 characters with `...` appended. */\n    body: string;\n    threadId: string;\n    messageId: string;\n  }\n  /** An inbound Kapso (WhatsApp) message. */\n  export interface KapsoMessageEvent {\n    phoneNumberId: string;\n    conversationId?: string;\n    messageId: string;\n    from?: string;\n    /** Kapso message type, such as `text` or `image`. */\n    type?: string;\n    /** The text, or a placeholder naming the type for a non-text message. */\n    text: string;\n  }\n  export type VcsProvider = "github" | "gitlab" | "azure-devops";\n  /**\n   * The provider object the event is about, as the provider names it. GitLab\n   * calls a pull request a merge request, and a comment a `note`.\n   */\n  export type VcsEventKind =\n    | "pull_request"\n    | "merge_request"\n    | "issue"\n    | "issue_comment"\n    | "note"\n    | "pull_request_review"\n    | "pipeline";\n  /**\n   * A webhook event from a connected code host. `action` is the provider\'s own\n   * value: `opened`, `closed`, `synchronize`, `merge`, `created`, `commented`, or,\n   * for a pipeline, its status such as `success` or `failed`. Fields a kind does\n   * not carry are absent.\n   */\n  export interface VcsEvent {\n    provider: VcsProvider;\n    kind: VcsEventKind;\n    action: string;\n    /** `owner/name` on GitHub and GitLab, the repository URL on Azure DevOps. */\n    repo: string;\n    /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */\n    number?: number;\n    title?: string;\n    body?: string | null;\n    /** Login of the user behind the event. Set for pull requests, merge requests, and Azure DevOps comments. */\n    author?: string;\n    url?: string;\n    merged?: boolean;\n    changedFiles?: number;\n    /** The review verdict, on a pull request review. */\n    reviewState?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.chat.route": {\n      event: ChatRouteEvent;\n      modify: ChatRouteModify;\n      result: PreResult<ChatRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.chat.message": {\n      event: ChatMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.approval.resolved": {\n      event: ApprovalResolvedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.budgetRefused": {\n      event: TaskBudgetRefusedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.email.received": {\n      event: EmailReceivedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.kapso.message": {\n      event: KapsoMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.vcs.event": {\n      event: VcsEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';
+  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | "bitbucket" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRequester?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    poolWakeAt?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | "bitbucket" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    resolvedEffort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    resolvedProfile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | "amp"\n      | "cursor"\n      | "grok"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  /** A Chat SDK message after its thread buffer flushed, before routing. */\n  export interface ChatRouteEvent {\n    /** Adapter name, such as `telegram` or `slack`. */\n    adapter: string;\n    channelId: string;\n    /** The Chat SDK thread id, prefixed with the adapter name. */\n    threadId: string;\n    /** The first buffered sender. */\n    userId: string;\n    userName?: string;\n    /** The buffered messages, joined. */\n    text: string;\n    /** True for an @mention and for a reply to one of the bot\'s messages. */\n    botMentioned: boolean;\n    isDirectMessage: boolean;\n    /** Platform chat type, such as Telegram `private`, `group`, `supergroup` or `channel`. */\n    chatType?: string;\n    /** Set for a Telegram supergroup with topics. */\n    isForum?: boolean;\n    /** A buffered message replies to one of the bot\'s own messages. */\n    replyToBot: boolean;\n    /** Set when earlier swarm tasks exist in this thread. */\n    threadContext?: {\n      adapter: string;\n      threadId: string;\n    };\n  }\n  export interface ChatRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        }\n      | {\n          kind: "workflow";\n          workflowId: string;\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  /** A Chat SDK message the swarm received or sent. */\n  export interface ChatMessageEvent {\n    adapter: string;\n    channelId: string;\n    threadId: string;\n    /** The sender, for an inbound message. */\n    userId?: string;\n    text: string;\n    direction: "inbound" | "outbound";\n    taskId?: string;\n    messageId?: string;\n  }\n  /**\n   * A person answered an approval request. Fires for workflow and standalone\n   * requests. Timeouts and cancellations do not emit it today.\n   */\n  export interface ApprovalResolvedEvent {\n    requestId: string;\n    status: "approved" | "rejected" | "timeout" | "cancelled";\n    responses: Record<string, unknown> | null;\n    /** Set when a workflow human-in-the-loop step asked. Absent for a standalone request. */\n    workflowRunId?: string;\n    workflowRunStepId?: string;\n    /** The task whose agent asked, for a standalone request. */\n    sourceTaskId?: string;\n  }\n  /** A task was refused because a daily spend budget is used up. */\n  export interface TaskBudgetRefusedEvent extends TaskEvent {\n    /** The agent the task was refused for. */\n    agentId: string;\n    /** Which budget refused it. The matching spend and budget fields are set. */\n    cause: "agent" | "global" | "user";\n    agentSpendUsd?: number;\n    agentBudgetUsd?: number;\n    globalSpendUsd?: number;\n    globalBudgetUsd?: number;\n    userSpendUsd?: number;\n    userBudgetUsd?: number;\n    /** ISO 8601 time the daily budget resets. */\n    resetAt: string;\n  }\n  /** An inbound AgentMail message. */\n  export interface EmailReceivedEvent {\n    inboxId: string;\n    /** The From header as sent. */\n    from: string;\n    subject: string;\n    /** The text body, or the HTML when there is no text, cut to 500 characters with `...` appended. */\n    body: string;\n    threadId: string;\n    messageId: string;\n  }\n  /** An inbound Kapso (WhatsApp) message. */\n  export interface KapsoMessageEvent {\n    phoneNumberId: string;\n    conversationId?: string;\n    messageId: string;\n    from?: string;\n    /** Kapso message type, such as `text` or `image`. */\n    type?: string;\n    /** The text, or a placeholder naming the type for a non-text message. */\n    text: string;\n  }\n  export type VcsProvider = "github" | "gitlab" | "azure-devops" | "bitbucket";\n  /**\n   * The provider object the event is about, as the provider names it. GitLab\n   * calls a pull request a merge request, and a comment a `note`.\n   */\n  export type VcsEventKind =\n    | "pull_request"\n    | "merge_request"\n    | "issue"\n    | "issue_comment"\n    | "note"\n    | "pull_request_review"\n    | "pipeline";\n  /**\n   * A webhook event from a connected code host. `action` is the provider\'s own\n   * value: `opened`, `closed`, `synchronize`, `merge`, `created`, `commented`, or,\n   * for a pipeline, its status such as `success` or `failed`. Fields a kind does\n   * not carry are absent.\n   */\n  export interface VcsEvent {\n    provider: VcsProvider;\n    kind: VcsEventKind;\n    action: string;\n    /** `owner/name` on GitHub and GitLab, `workspace/repo_slug` on Bitbucket, the repository URL on Azure DevOps. */\n    repo: string;\n    /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */\n    number?: number;\n    title?: string;\n    body?: string | null;\n    /** Login of the user behind the event. Set for pull requests, merge requests, and Azure DevOps comments. */\n    author?: string;\n    url?: string;\n    merged?: boolean;\n    changedFiles?: number;\n    /** The review verdict, on a pull request review. */\n    reviewState?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.chat.route": {\n      event: ChatRouteEvent;\n      modify: ChatRouteModify;\n      result: PreResult<ChatRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.chat.message": {\n      event: ChatMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.approval.resolved": {\n      event: ApprovalResolvedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.budgetRefused": {\n      event: TaskBudgetRefusedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.email.received": {\n      event: EmailReceivedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.kapso.message": {\n      event: KapsoMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.vcs.event": {\n      event: VcsEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';

package/src/extensions/contract.ts

@@ -337,7 +337,7 @@ export interface KapsoMessageEvent {
   text: string;
 }
 
-export type VcsProvider = "github" | "gitlab" | "azure-devops";
+export type VcsProvider = "github" | "gitlab" | "azure-devops" | "bitbucket";
 
 /**
  * The provider object the event is about, as the provider names it. GitLab
@@ -362,7 +362,7 @@ export interface VcsEvent {
   provider: VcsProvider;
   kind: VcsEventKind;
   action: string;
-  /** `owner/name` on GitHub and GitLab, the repository URL on Azure DevOps. */
+  /** `owner/name` on GitHub and GitLab, `workspace/repo_slug` on Bitbucket, the repository URL on Azure DevOps. */
   repo: string;
   /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */
   number?: number;

package/src/extensions/post-bridge.ts

@@ -301,6 +301,7 @@ const VCS_PROVIDERS: ReadonlySet<string> = new Set<VcsProvider>([
   "github",
   "gitlab",
   "azure-devops",
+  "bitbucket",
 ]);
 const VCS_KINDS: ReadonlySet<string> = new Set<VcsEventKind>([
   "pull_request",

package/src/github/handlers.ts

@@ -307,7 +307,7 @@ export async function handlePullRequest(
     }
 
     // Find the related task
-    const task = await findTaskByVcs(repository.full_name, pr.number);
+    const task = await findTaskByVcs(repository.full_name, pr.number, "github");
     if (!task) {
       console.log(`[GitHub] No active task found for PR #${pr.number} to cancel`);
       return { created: false };
@@ -337,7 +337,7 @@ export async function handlePullRequest(
     }
 
     // Check if there's an existing active task for this PR — skip duplicate review tasks
-    const existingTask = await findTaskByVcs(repository.full_name, pr.number);
+    const existingTask = await findTaskByVcs(repository.full_name, pr.number, "github");
     if (existingTask) {
       console.log(
         `[GitHub] Skipping review task for PR #${pr.number} — active task ${existingTask.id} already exists`,
@@ -419,7 +419,7 @@ export async function handlePullRequest(
     }
 
     // Find the related task
-    const task = await findTaskByVcs(repository.full_name, pr.number);
+    const task = await findTaskByVcs(repository.full_name, pr.number, "github");
     if (!task) {
       console.log(`[GitHub] No active task found for PR #${pr.number} to cancel`);
       return { created: false };
@@ -703,7 +703,7 @@ export async function handleIssue(
     }
 
     // Find the related task
-    const task = await findTaskByVcs(repository.full_name, issue.number);
+    const task = await findTaskByVcs(repository.full_name, issue.number, "github");
     if (!task) {
       console.log(`[GitHub] No active task found for issue #${issue.number} to cancel`);
       return { created: false };
@@ -913,7 +913,7 @@ export async function handleComment(
 
   // Check if there's an existing task for this PR/Issue
   const existingTask = targetNumber
-    ? await findTaskByVcs(repository.full_name, targetNumber)
+    ? await findTaskByVcs(repository.full_name, targetNumber, "github")
     : null;
 
   // Build task description
@@ -1365,7 +1365,7 @@ export async function handlePullRequestReview(
   }
 
   // Find any existing task for this PR
-  const existingTask = await findTaskByVcs(repository.full_name, pr.number);
+  const existingTask = await findTaskByVcs(repository.full_name, pr.number, "github");
 
   // Only notify for PRs where bot is creator or already has a task
   const isBotCreator = isBotAssignee(pr.user.login);

package/src/gitlab/handlers.ts

@@ -207,7 +207,7 @@ export async function handleMergeRequest(
     case "close":
     case "merge": {
       // Cancel existing tasks for this MR
-      const existingTask = await findTaskByVcs(repo, mr.iid);
+      const existingTask = await findTaskByVcs(repo, mr.iid, "gitlab");
       if (existingTask) {
         const reason = action === "merge" ? "MR was merged" : "MR was closed";
         console.log(`[GitLab] Cancelling task ${existingTask.id} — ${reason}`);
@@ -218,7 +218,7 @@ export async function handleMergeRequest(
 
     case "update": {
       // Check if there's an active task for this MR — if so, notify about the update
-      const task = await findTaskByVcs(repo, mr.iid);
+      const task = await findTaskByVcs(repo, mr.iid, "gitlab");
       if (task) {
         console.log(`[GitLab] MR #${mr.iid} updated, active task exists: ${task.id}`);
         // Don't create a new task — the worker will see the changes
@@ -318,7 +318,7 @@ export async function handleIssue(
     }
 
     case "close": {
-      const existingTask = await findTaskByVcs(repo, issue.iid);
+      const existingTask = await findTaskByVcs(repo, issue.iid, "gitlab");
       if (existingTask) {
         console.log(`[GitLab] Cancelling task ${existingTask.id} — issue closed`);
         await failTask(existingTask.id, "Issue was closed");
@@ -375,7 +375,7 @@ export async function handleNote(event: NoteEvent): Promise<{ created: boolean;
   }
 
   // Check if there's already an active task for this entity
-  const existingTask = targetNumber ? await findTaskByVcs(repo, targetNumber) : null;
+  const existingTask = targetNumber ? await findTaskByVcs(repo, targetNumber, "gitlab") : null;
 
   const existingTaskNote = existingTask
     ? `\n\n_Note: There's an active task (${existingTask.id}) for this ${entityLabel}._`
@@ -462,7 +462,7 @@ export async function handlePipeline(
   }
 
   // Only create task if there's already an active task for this MR
-  const existingTask = await findTaskByVcs(repo, mrIid);
+  const existingTask = await findTaskByVcs(repo, mrIid, "gitlab");
   if (!existingTask) {
     return { created: false };
   }

package/src/http/assets.ts

@@ -5,6 +5,7 @@ import { auditAssetKeys } from "../be/asset-key-audit";
 import { AssetKeyAuthorizationError, authorizeAssetKeyWrite } from "../be/asset-key-auth";
 import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
+  AssetKeyMovesBlockedError,
   getDb,
   getDbClient,
   getRootTaskChain,
@@ -25,6 +26,7 @@ import {
 import { getRequestAuth } from "../utils/request-auth-context";
 import { requestPrincipal } from "./request-principal";
 import { route } from "./route-def";
+import { canReadSession, hasSessionWrite, SESSION_READ_DENIED } from "./session-access";
 import { jsonError } from "./utils";
 
 const AssetKeyAuditIssueSchema = z.object({
@@ -184,7 +186,7 @@ const moveAssetRoute = route({
   },
 });
 
-async function canMutateTaskNamespace(
+export async function canMutateTaskNamespace(
   task: { id: string; agentId: string | null; creatorAgentId?: string },
   myAgentId: string | undefined,
   req: IncomingMessage,
@@ -322,6 +324,16 @@ export async function handleAssets(
         jsonError(res, "Asset not found", 404);
         return true;
       }
+      if (!(await hasSessionWrite(req, myAgentId, task.id))) {
+        jsonError(
+          res,
+          (await canReadSession(req, myAgentId, task.id))
+            ? "You can view this session but not move it."
+            : SESSION_READ_DENIED,
+          403,
+        );
+        return true;
+      }
       // Only the tasks checked here move: a subtask created after this read stays put.
       const tasks = parsed.body.cascade ? await getRootTaskChain(task.id) : [task];
       for (const target of tasks) {
@@ -382,7 +394,7 @@ export async function handleAssets(
         return true;
       }
       const message = error instanceof Error ? error.message : String(error);
-      jsonError(res, message, message.includes("blocked until") ? 409 : 400);
+      jsonError(res, message, error instanceof AssetKeyMovesBlockedError ? 409 : 400);
     }
     return true;
   }

package/src/http/core.ts

@@ -29,6 +29,12 @@ import {
 import { enqueueAdmissionRow } from "../be/rbac-audit";
 import { getUserGrant } from "../be/rbac-roles";
 import { syncTelemetryEnabled } from "../be/telemetry-enable";
+import {
+  initBitbucket,
+  isBitbucketEnabled,
+  resetBitbucket,
+  resetBitbucketBotCache,
+} from "../bitbucket";
 import { initGitHub, resetGitHub } from "../github";
 import { initGitLab, isGitLabEnabled, resetGitLab } from "../gitlab";
 import { restartChatSdkIfConfigChanged } from "../integrations/chat-sdk/runtime";
@@ -248,6 +254,12 @@ async function reloadGlobalConfigsAndIntegrationsInner(): Promise<ReloadConfigRe
   teardownAzureDevOpsOutbound();
   if (isAzureDevOpsEnabled()) initAzureDevOpsOutbound();
 
+  // Same reset-then-init: the webhook secret and bot account id are cached.
+  resetBitbucket();
+  resetBitbucketBotCache();
+  initBitbucket();
+  if (isBitbucketEnabled()) integrations.push("bitbucket");
+
   resetLinear();
   if (await initLinear()) integrations.push("linear");
 

package/src/http/index.ts

@@ -33,6 +33,7 @@ import { loadSecretRegistry } from "../be/secret-registry";
 import { seedLegacyCapabilitiesConfig } from "../be/seed-capabilities";
 import { initApiTelemetry } from "../be/telemetry-enable";
 import { startWorkerNudgeListener } from "../be/worker-nudge-listener";
+import { initBitbucket } from "../bitbucket";
 import {
   loadEnabledExtensions,
   setExtensionLoopbackBaseUrl,
@@ -798,6 +799,9 @@ httpServer
     initAzureDevOps();
     initAzureDevOpsOutbound();
 
+    // Initialize Bitbucket Cloud webhook handler (if configured)
+    initBitbucket();
+
     // Initialize AgentMail webhook handler (if configured)
     initAgentMail();