@desplega.ai/agent-swarm 1.149.1 → 1.151.0

package/src/commands/runner.ts

@@ -71,6 +71,7 @@ import {
   buildResumeContextPreamble,
   prependContextPreamble,
 } from "./context-preamble.ts";
+import { type CredentialRefreshState, refreshCredentialStatus } from "./credential-refresh.ts";
 import {
   awaitCredentials,
   BootMaxWaitExceededError,
@@ -91,10 +92,8 @@ import {
   buildLatestModelReport,
   isCredCheckDisabled,
   reportAcpStatus,
-  reportCredStatus,
   reportLatestModel,
   sendCredStatusReport,
-  shouldRefreshBedrockStatus,
 } from "./provider-credentials.ts";
 import {
   type ResumeSessionCandidate,
@@ -4972,13 +4971,13 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   const cancelledSignaled = new Set<string>();
   const steeringDispatchState = isSteeringEnabled() ? createSteeringDispatchState() : null;
 
-  // Migration 055 — cache the harness_provider value used when we last
-  // built a `cred_status` snapshot. Re-runs the post-task check only when
-  // the resolved provider changes. Section 4 of the swarm_config-overrides-
-  // HARNESS_PROVIDER work makes this dynamic: state.harnessProvider is
-  // reconciled below from `swarm_config`, so an operator's change reaches
-  // here without a worker restart.
-  let cachedCredHarnessProvider: string | null = null;
+  // Readiness acknowledged by the API, shared by boot and steady-state checks.
+  const credentialRefreshState: CredentialRefreshState = {
+    harnessProvider: null,
+    ready: null,
+    lastRefreshAt: 0,
+    inFlight: false,
+  };
 
   // Throttle for live HARNESS_PROVIDER reconciliation. Each reconciliation
   // calls `fetchResolvedEnv` which also re-resolves credential pools — we
@@ -4994,16 +4993,6 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   let lastServerCapsRefreshAt = 0;
   const SERVER_CAPS_REFRESH_INTERVAL_MS = 300_000;
 
-  // Throttle for the periodic Bedrock model-enumeration refresh. The credential
-  // report below only re-runs on a harness_provider change (boot + provider
-  // swap), so enabling Bedrock access after boot would otherwise never reach the
-  // picker. This timer re-runs the enumeration on a fixed interval, decoupled
-  // from the harness-change gate, so the UI stays accurate. 5 minutes keeps it
-  // cheap (one bounded AWS enumeration per tick) while still surfacing newly
-  // granted access within a few minutes.
-  let lastBedrockRefreshAt = 0;
-  const BEDROCK_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
-
   // Fresh per boot and shared by registration, ping, and close: a restarted
   // process is a new runtime, but one process presents one identity.
   const runtimeInstanceId = crypto.randomUUID();
@@ -5055,7 +5044,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           ? `${basePrompt}\n\n${additionalSystemPrompt}`
           : basePrompt;
         promptRebuiltForProvider = true;
-        cachedCredHarnessProvider = null;
+        credentialRefreshState.harnessProvider = null;
         agentVisibleChanged = true;
         console.log(
           `[${role}] [harness] Swapped to ${resolvedProvider} (basePrompt rebuilt: ${basePrompt.length} chars)`,
@@ -5206,7 +5195,6 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   // CRED_CHECK_DISABLE=1 opts out entirely: the worker trusts the operator
   // and starts polling immediately, with a NULL `cred_status` row that the
   // dashboard surfaces as "unreported."
-  cachedCredHarnessProvider = state.harnessProvider;
   if (isCredCheckDisabled(process.env)) {
     console.log(`[${role}] CRED_CHECK_DISABLE=1, skipping credential checks`);
   } else {
@@ -5331,6 +5319,9 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           log: (line) => console.warn(`[${role}] ${line}`),
         },
       );
+      credentialRefreshState.harnessProvider = state.harnessProvider;
+      credentialRefreshState.ready = bootCredSnapshot?.ready ?? true;
+      credentialRefreshState.lastRefreshAt = Date.now();
     } catch (error) {
       console.error(`[${role}] Failed to report credential readiness after recovery: ${error}`);
       process.exit(1);
@@ -5915,41 +5906,17 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       }
     }
 
-    // Migration 055 — post-task credential refresh, cache-keyed on the
-    // *resolved* harness_provider. Re-runs the snapshot when the provider
-    // changes (boot, or after a live swap above) so the dashboard shows
-    // up-to-date credential status for the active adapter.
-    if (!isCredCheckDisabled(process.env)) {
-      const currentHarness = state.harnessProvider;
-      if (currentHarness !== cachedCredHarnessProvider) {
-        cachedCredHarnessProvider = currentHarness;
-        buildCredStatusReport(currentHarness, process.env, {}, "post_task")
-          .then((snap) => reportCredStatus(apiUrl, apiKey, agentId, runtimeInstanceId, snap))
-          .catch((err) =>
-            console.warn(`[${role}] cred_status post_task report failed (non-fatal): ${err}`),
-          );
-      } else if (
-        shouldRefreshBedrockStatus({
-          harnessProvider: currentHarness,
-          env: process.env,
-          lastRefreshAt: lastBedrockRefreshAt,
-          now: Date.now(),
-          intervalMs: BEDROCK_REFRESH_INTERVAL_MS,
-        })
-      ) {
-        // Bedrock enumeration drifts independently of the harness_provider:
-        // access granted (or revoked) in the AWS console after boot won't flip
-        // the provider, so the harness-change gate above never fires. Re-run the
-        // enumeration on the throttled interval so the picker reflects the live
-        // account state. One bounded AWS round-trip per tick.
-        lastBedrockRefreshAt = Date.now();
-        buildCredStatusReport(currentHarness, process.env, {}, "post_task")
-          .then((snap) => reportCredStatus(apiUrl, apiKey, agentId, runtimeInstanceId, snap))
-          .catch((err) =>
-            console.warn(`[${role}] bedrock enumeration refresh failed (non-fatal): ${err}`),
-          );
-      }
-    }
+    // Recheck provider changes, blocked credentials, and Bedrock enumeration.
+    // The helper honors CRED_CHECK_DISABLE, throttles retries, and prevents
+    // overlapping reports while keeping polling responsive.
+    refreshCredentialStatus(
+      apiConfig,
+      credentialRefreshState,
+      state.harnessProvider,
+      process.env,
+    ).catch((err) =>
+      console.warn(`[${role}] cred_status post_task refresh failed (non-fatal): ${err}`),
+    );
 
     // Periodic VCS detection for running tasks (fire-and-forget, throttled per task)
     const now = Date.now();
@@ -5970,7 +5937,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
 
     // Check for cancelled tasks and signal their subprocesses. Deliberately
     // NOT gated on steeringDispatchState — cancellation abort must keep
-    // working when steering dispatch is off (STEERING_ENABLED unset).
+    // working when steering dispatch is off (STEERING_ENABLED=false).
     if (state.activeTasks.size > 0) {
       for (const [taskId, task] of state.activeTasks) {
         if (cancelledSignaled.has(taskId)) continue; // Already sent SIGTERM

package/src/extensions/apply-task-create.ts

@@ -0,0 +1,135 @@
+import type { RequestInfo } from "../tools/utils";
+import { type CreateTaskOptions, CreateTaskOptionsSchema } from "../types";
+import { scrubSecrets } from "../utils/secret-scrubber";
+import type { TaskCreateModify, TaskCreateOrigin } from "./contract";
+import { dispatchPre, extensionIdForAgent, listRegistered } from "./dispatcher";
+
+const MODIFIABLE_OPTION_KEYS = [
+  "agentId",
+  "creatorAgentId",
+  "source",
+  "taskType",
+  "tags",
+  "priority",
+  "dependsOn",
+  "offeredTo",
+  "vcsProvider",
+  "vcsRepo",
+  "vcsEventType",
+  "vcsNumber",
+  "vcsCommentId",
+  "vcsAuthor",
+  "vcsUrl",
+  "vcsInstallationId",
+  "vcsNodeId",
+  "agentmailInboxId",
+  "agentmailMessageId",
+  "agentmailThreadId",
+  "mentionMessageId",
+  "mentionChannelId",
+  "dir",
+  "model",
+  "modelTier",
+  "effort",
+  "outputSchema",
+  "followUpConfig",
+  "bypassTrackerContextDedup",
+] as const satisfies readonly Exclude<keyof TaskCreateModify, "description">[];
+
+type AssertNever<T extends never> = T;
+type _AllModifiableOptionKeysCovered = AssertNever<
+  Exclude<keyof TaskCreateModify, "description" | (typeof MODIFIABLE_OPTION_KEYS)[number]>
+>;
+
+const MODIFIABLE_OPTION_KEY_SET = new Set<string>(MODIFIABLE_OPTION_KEYS);
+
+type ApplyPreTaskCreateArgs = {
+  description: string;
+  options: CreateTaskOptions;
+  origin: TaskCreateOrigin;
+  requestInfo?: RequestInfo;
+};
+
+export type ApplyPreTaskCreateResult =
+  | {
+      kind: "blocked";
+      reason: string;
+      extension: { id: string; name: string };
+    }
+  | { kind: "proceed"; description: string; options: CreateTaskOptions };
+
+function warnDroppedKey(extensionName: string, key: string): void {
+  console.warn(
+    scrubSecrets(
+      `[extensions] pre.task.create ignored disallowed key "${key}" from extension "${extensionName}"`,
+    ),
+  );
+}
+
+export async function applyPreTaskCreate(
+  args: ApplyPreTaskCreateArgs,
+): Promise<ApplyPreTaskCreateResult> {
+  const creatingExtensionId = extensionIdForAgent(args.requestInfo?.agentId);
+  const creatingExtension = creatingExtensionId
+    ? listRegistered().find((loaded) => loaded.record.id === creatingExtensionId)
+    : undefined;
+  const origin = creatingExtension
+    ? (`extension:${creatingExtension.record.name}` as const)
+    : args.origin;
+
+  const result = await dispatchPre(
+    "pre.task.create",
+    {
+      description: args.description,
+      options: args.options,
+      origin,
+      requestInfo: args.requestInfo,
+    },
+    {
+      skipExtensionId: creatingExtensionId,
+      transformModify: ({ data, currentPayload, extension }) => {
+        const currentOptions = (currentPayload.options ?? {}) as CreateTaskOptions;
+        const filtered: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(data)) {
+          if (key === "description") {
+            if (typeof value !== "string" || value.trim().length === 0) {
+              throw new Error("Extension task description must be a non-empty string");
+            }
+            filtered.description = value;
+            continue;
+          }
+          if (
+            !MODIFIABLE_OPTION_KEY_SET.has(key) ||
+            (key === "dir" && currentOptions.parentTaskId)
+          ) {
+            warnDroppedKey(extension.name, key);
+            continue;
+          }
+          filtered[key] = value;
+        }
+
+        const { description: _description, ...optionChanges } = filtered;
+        CreateTaskOptionsSchema.parse({ ...currentOptions, ...optionChanges });
+        return filtered;
+      },
+    },
+  );
+
+  if (result.action === "block") {
+    return {
+      kind: "blocked",
+      reason: result.reason,
+      extension: result.extension,
+    };
+  }
+  if (result.action === "continue") {
+    return { kind: "proceed", description: args.description, options: args.options };
+  }
+
+  const { description, ...optionChanges } = result.data;
+  return {
+    kind: "proceed",
+    description: description ?? args.description,
+    options: CreateTaskOptionsSchema.parse({ ...args.options, ...optionChanges }),
+  };
+}

package/src/extensions/bundle-path.ts

@@ -0,0 +1,10 @@
+export function isSafeBundlePath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    path.length <= 256 &&
+    !path.startsWith("/") &&
+    !path.includes("\\") &&
+    !path.includes("\0") &&
+    path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..")
+  );
+}

package/src/extensions/contract-runtime.ts

@@ -0,0 +1,7 @@
+export function block(reason: string): { action: "block"; reason: string } {
+  return { action: "block", reason };
+}
+
+export function modify<T>(data: T): { action: "modify"; data: T } {
+  return { action: "modify", data };
+}

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

@@ -0,0 +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      | "system"\n      | "linear"\n      | "jira"\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" | 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    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    inheritParentRoutingAffinity?: 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            | 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      | "system"\n      | "linear"\n      | "jira";\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    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" | 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    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    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      | 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            | 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 ExtensionManifest {\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      skills?: string[];\n      workflows?: string[];\n      schedules?: string[];\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  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  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.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.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

@@ -0,0 +1,270 @@
+// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.
+import type { SwarmSdk } from "swarm-sdk";
+import type { z } from "zod";
+import type { RequestInfo } from "../tools/utils";
+import type { ActiveSession, AgentTask, CreateTaskOptions } from "../types";
+
+export type Runtime = "api" | "worker";
+
+export interface ExtensionManifest {
+  name: string;
+  description: string;
+  version: string;
+  runtime: Runtime;
+  assets: {
+    hooks: string;
+    skills?: string[];
+    workflows?: string[];
+    schedules?: string[];
+  };
+  homepage?: string;
+  author?: string;
+}
+
+export interface HooksModule {
+  default: SwarmExtension;
+  config?: z.ZodTypeAny;
+}
+
+export interface ExtensionState {
+  get<T = unknown>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  incr(key: string, by?: number): Promise<number>;
+  del(key: string): Promise<void>;
+}
+
+export interface ExtensionLogger {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+type ConfigFor<M extends ExtensionManifest> = M extends {
+  config: infer C extends z.ZodTypeAny;
+}
+  ? z.infer<C>
+  : Record<string, unknown>;
+
+export interface ApiCtx<Config = Record<string, unknown>> {
+  swarm: SwarmSdk;
+  state: ExtensionState;
+  config: Config;
+  log: ExtensionLogger;
+  signal: AbortSignal;
+  event: {
+    name: keyof SwarmEventMap;
+    at: string;
+    extension: { id: string; version: number };
+  };
+}
+
+export interface WorkerCtx<Config = Record<string, unknown>> extends Omit<ApiCtx<Config>, "swarm"> {
+  swarm: SwarmSdk;
+  worker: { agentId: string; taskId: string; harness: string };
+}
+
+export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"
+  ? ApiCtx<ConfigFor<M>>
+  : WorkerCtx<ConfigFor<M>>;
+
+export type PreResult<Modify> =
+  | void
+  | { action: "continue" }
+  | { action: "modify"; data: Modify }
+  | { action: "block"; reason: string };
+
+export type TaskCreateOrigin =
+  | "rest"
+  | "app"
+  | "mcp"
+  | "slack"
+  | "schedule"
+  | "workflow"
+  | "webhook"
+  | "followUp"
+  | `extension:${string}`;
+
+export interface TaskCreateEvent {
+  options: CreateTaskOptions;
+  description: string;
+  origin: TaskCreateOrigin;
+  requestInfo?: RequestInfo;
+}
+
+export type TaskCreateModify = Partial<
+  Pick<
+    CreateTaskOptions,
+    | "agentId"
+    | "creatorAgentId"
+    | "source"
+    | "taskType"
+    | "tags"
+    | "priority"
+    | "dependsOn"
+    | "offeredTo"
+    | "vcsProvider"
+    | "vcsRepo"
+    | "vcsEventType"
+    | "vcsNumber"
+    | "vcsCommentId"
+    | "vcsAuthor"
+    | "vcsUrl"
+    | "vcsInstallationId"
+    | "vcsNodeId"
+    | "agentmailInboxId"
+    | "agentmailMessageId"
+    | "agentmailThreadId"
+    | "mentionMessageId"
+    | "mentionChannelId"
+    | "dir"
+    | "model"
+    | "modelTier"
+    | "effort"
+    | "outputSchema"
+    | "followUpConfig"
+    | "bypassTrackerContextDedup"
+  >
+> & { description?: string };
+
+export interface TaskFollowUpEvent {
+  completedTask: AgentTask;
+  status: "completed" | "failed";
+  output?: string;
+  failureReason?: string;
+  workerAgentId: string;
+  leadAgentId: string;
+  summary: string;
+}
+
+export type TaskFollowUpModify = Partial<
+  Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">
+> & { description?: string };
+
+export interface SlackRouteEvent {
+  channelId: string;
+  userId: string;
+  text: string;
+  threadTs?: string;
+  botMentioned: boolean;
+  threadContext?: { channelId: string; threadTs: string };
+}
+
+export interface SlackRouteModify {
+  target: { kind: "agent"; agentId: string } | { kind: "lead" } | { kind: "broadcast" };
+}
+
+export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";
+export type HeartbeatAction = "supersede-resume" | "fail" | "record";
+
+export interface HeartbeatRemediateEvent {
+  task: AgentTask;
+  session?: ActiveSession;
+  classification: HeartbeatClassification;
+  proposedAction: HeartbeatAction;
+  reason: string;
+  taskAgeMs: number;
+  sessionHeartbeatAgeMs?: number;
+}
+
+export interface HeartbeatRemediateModify {
+  proposedAction: HeartbeatAction;
+}
+
+export interface ToolCallEvent {
+  tool: string;
+  args: unknown;
+  requestInfo: RequestInfo;
+}
+
+export interface ToolCallModify {
+  args: unknown;
+}
+
+export interface TaskEvent {
+  task: AgentTask;
+}
+
+export interface TaskCompletedEvent extends TaskEvent {
+  output: string;
+}
+
+export interface TaskFailedEvent extends TaskEvent {
+  failureReason: string;
+}
+
+export interface TaskSupersededEvent extends TaskEvent {
+  supersededBy: string;
+}
+
+export interface TaskProgressEvent extends TaskEvent {
+  progress: string;
+}
+
+export interface SlackMessageEvent {
+  channelId: string;
+  userId: string;
+  text: string;
+  threadTs?: string;
+  taskId?: string;
+}
+
+export interface ToolCallCompletedEvent extends ToolCallEvent {
+  result: unknown;
+  durationMs: number;
+}
+
+export interface SwarmEventMap {
+  "pre.task.create": {
+    event: TaskCreateEvent;
+    modify: TaskCreateModify;
+    result: PreResult<TaskCreateModify>;
+  };
+  "pre.task.followUp": {
+    event: TaskFollowUpEvent;
+    modify: TaskFollowUpModify;
+    result: PreResult<TaskFollowUpModify>;
+  };
+  "pre.slack.route": {
+    event: SlackRouteEvent;
+    modify: SlackRouteModify;
+    result: PreResult<SlackRouteModify>;
+  };
+  "pre.heartbeat.remediate": {
+    event: HeartbeatRemediateEvent;
+    modify: HeartbeatRemediateModify;
+    result: PreResult<HeartbeatRemediateModify>;
+  };
+  "pre.tool.call": {
+    event: ToolCallEvent;
+    modify: ToolCallModify;
+    result: PreResult<ToolCallModify>;
+  };
+  "post.task.created": { event: TaskEvent; modify: never; result: void };
+  "post.task.completed": { event: TaskCompletedEvent; modify: never; result: void };
+  "post.task.failed": { event: TaskFailedEvent; modify: never; result: void };
+  "post.task.cancelled": { event: TaskEvent; modify: never; result: void };
+  "post.task.superseded": { event: TaskSupersededEvent; modify: never; result: void };
+  "post.task.progress": { event: TaskProgressEvent; modify: never; result: void };
+  "post.slack.message": { event: SlackMessageEvent; modify: never; result: void };
+  "post.tool.call": { event: ToolCallCompletedEvent; modify: never; result: void };
+}
+
+export interface ExtensionApi<
+  M extends ExtensionManifest = ExtensionManifest & { runtime: "api" },
+> {
+  on<E extends keyof SwarmEventMap>(
+    event: E,
+    handler: (
+      event: SwarmEventMap[E]["event"],
+      ctx: CtxFor<M>,
+    ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],
+    opts?: { priority?: number },
+  ): void;
+}
+
+export type SwarmExtension<M extends ExtensionManifest = ExtensionManifest & { runtime: "api" }> = (
+  api: ExtensionApi<M>,
+) => void;
+
+export { block, modify } from "./contract-runtime";