@desplega.ai/agent-swarm 2.5.3 → 2.6.0

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

@@ -2,7 +2,13 @@ import { explicitModelErrorForAgent } from "../be/model-validation";
 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 { workflowEventBus } from "../workflows/event-bus";
+import type {
+  TaskBlockedEvent,
+  TaskCreateEvent,
+  TaskCreateModify,
+  TaskCreateOrigin,
+} from "./contract";
 import { dispatchPre, extensionIdForAgent, listRegistered } from "./dispatcher";
 
 const MODIFIABLE_OPTION_KEYS = [
@@ -49,6 +55,7 @@ type ApplyPreTaskCreateArgs = {
   options: CreateTaskOptions;
   origin: TaskCreateOrigin;
   requestInfo?: RequestInfo;
+  slack?: TaskCreateEvent["slack"];
   /** The caller's escape hatch for an uncatalogued `model`; the harness check ignores it. */
   allowCustomModel?: boolean;
 };
@@ -69,6 +76,14 @@ function warnDroppedKey(extensionName: string, key: string): void {
   );
 }
 
+function scrubFields<T extends object>(fields: T): T {
+  return Object.fromEntries(
+    Object.entries(fields)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => [key, typeof value === "string" ? scrubSecrets(value) : value]),
+  ) as T;
+}
+
 export async function applyPreTaskCreate(
   args: ApplyPreTaskCreateArgs,
 ): Promise<ApplyPreTaskCreateResult> {
@@ -80,6 +95,48 @@ export async function applyPreTaskCreate(
     ? (`extension:${creatingExtension.record.name}` as const)
     : args.origin;
 
+  const blocked = (
+    reason: string,
+    extension: TaskBlockedEvent["extension"],
+  ): ApplyPreTaskCreateResult => {
+    const { options, requestInfo } = args;
+    const event: TaskBlockedEvent = {
+      extension,
+      reason: scrubSecrets(reason),
+      origin,
+      source: options.source,
+      requester: scrubFields({
+        userId: options.requestedByUserId,
+        agentId: requestInfo?.agentId ?? options.creatorAgentId,
+        slackUserId: options.slackUserId,
+      }),
+      context: scrubFields({
+        contextKey: options.contextKey ?? requestInfo?.contextKey,
+        scheduleId: options.scheduleId,
+        workflowRunId: options.workflowRunId,
+        workflowRunStepId: options.workflowRunStepId,
+        parentTaskId: options.parentTaskId,
+        vcsRepo: options.vcsRepo,
+        vcsNumber: options.vcsNumber,
+        slackChannelId: options.slackChannelId,
+        slackThreadTs: options.slackThreadTs,
+      }),
+      description: scrubSecrets(args.description).slice(0, 500),
+    };
+    try {
+      workflowEventBus.emit("task.create_blocked", {
+        ...event,
+        skipExtensionId: creatingExtensionId,
+      });
+    } catch (error) {
+      console.error(
+        "[extensions] task.create_blocked event not emitted:",
+        scrubSecrets(error instanceof Error ? error.message : String(error)),
+      );
+    }
+    return { kind: "blocked", reason: event.reason, extension };
+  };
+
   // The last extension that rewrote `model` or `agentId`. The final pair is re-checked
   // against the assignee's harness, because the caller validated the pre-hook pair only.
   let modelEditor: { id: string; name: string } | undefined;
@@ -90,6 +147,7 @@ export async function applyPreTaskCreate(
       options: args.options,
       origin,
       requestInfo: args.requestInfo,
+      ...(args.slack ? { slack: args.slack } : {}),
     },
     {
       skipExtensionId: creatingExtensionId,
@@ -125,11 +183,7 @@ export async function applyPreTaskCreate(
   );
 
   if (result.action === "block") {
-    return {
-      kind: "blocked",
-      reason: result.reason,
-      extension: result.extension,
-    };
+    return blocked(result.reason, result.extension);
   }
   if (result.action === "continue") {
     return { kind: "proceed", description: args.description, options: args.options };
@@ -146,11 +200,10 @@ export async function applyPreTaskCreate(
       agentId: options.agentId,
     });
     if (modelError) {
-      return {
-        kind: "blocked",
-        reason: `pre.task.create rewrite from extension "${modelEditor.name}" is invalid: ${modelError}`,
-        extension: modelEditor,
-      };
+      return blocked(
+        `pre.task.create rewrite from extension "${modelEditor.name}" is invalid: ${modelError}`,
+        modelEditor,
+      );
     }
   }
   return {

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      | "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';
+  '// 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      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "linear"\n      | "jira"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "system"\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      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "linear"\n      | "jira"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "system"\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    /** Slack ingress metadata; not persisted or writable through modify. */\n    slack?: {\n      trigger: "mention" | "thread-buffer";\n      messages: {\n        ts: string;\n        userId: string;\n        text: string;\n      }[];\n    };\n  }\n  /** A pre.task.create hook blocked a task before it was created. */\n  export interface TaskBlockedEvent {\n    /** The extension that blocked, or whose model/agent rewrite was rejected. */\n    extension: {\n      id: string;\n      name: string;\n    };\n    /** The scrubbed block reason. */\n    reason: string;\n    origin: TaskCreateOrigin;\n    source?: AgentTask["source"];\n    requester: {\n      userId?: string;\n      agentId?: string;\n      slackUserId?: string;\n    };\n    context?: {\n      contextKey?: string;\n      scheduleId?: string;\n      workflowRunId?: string;\n      workflowRunStepId?: string;\n      parentTaskId?: string;\n      vcsRepo?: string;\n      vcsNumber?: number;\n      slackChannelId?: string;\n      slackThreadTs?: string;\n    };\n    /** The original task description, scrubbed and cut to 500 characters. */\n    description: string;\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.blocked": {\n      event: TaskBlockedEvent;\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

@@ -117,6 +117,35 @@ export interface TaskCreateEvent {
   description: string;
   origin: TaskCreateOrigin;
   requestInfo?: RequestInfo;
+  /** Slack ingress metadata; not persisted or writable through modify. */
+  slack?: {
+    trigger: "mention" | "thread-buffer";
+    messages: { ts: string; userId: string; text: string }[];
+  };
+}
+
+/** A pre.task.create hook blocked a task before it was created. */
+export interface TaskBlockedEvent {
+  /** The extension that blocked, or whose model/agent rewrite was rejected. */
+  extension: { id: string; name: string };
+  /** The scrubbed block reason. */
+  reason: string;
+  origin: TaskCreateOrigin;
+  source?: AgentTask["source"];
+  requester: { userId?: string; agentId?: string; slackUserId?: string };
+  context?: {
+    contextKey?: string;
+    scheduleId?: string;
+    workflowRunId?: string;
+    workflowRunStepId?: string;
+    parentTaskId?: string;
+    vcsRepo?: string;
+    vcsNumber?: number;
+    slackChannelId?: string;
+    slackThreadTs?: string;
+  };
+  /** The original task description, scrubbed and cut to 500 characters. */
+  description: string;
 }
 
 export type TaskCreateModify = Partial<
@@ -414,6 +443,7 @@ export interface SwarmEventMap {
     result: PreResult<ToolCallModify>;
   };
   "post.task.created": { event: TaskEvent; modify: never; result: void };
+  "post.task.blocked": { event: TaskBlockedEvent; 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 };

package/src/extensions/dispatcher.ts

@@ -148,6 +148,10 @@ export function runContext(event: keyof SwarmEventMap, payload: unknown): RunCon
       agentId = requestAgent ?? stringField(payload, "options", "agentId");
       subject = `${stringField(payload, "origin") ?? "?"}: ${snippet(field(payload, "description"))}`;
       break;
+    case "post.task.blocked":
+      agentId = stringField(payload, "requester", "agentId");
+      subject = `${stringField(payload, "origin") ?? "?"}: ${stringField(payload, "extension", "name") ?? "?"}`;
+      break;
     case "pre.task.followUp":
       agentId = stringField(payload, "workerAgentId");
       subject =

package/src/extensions/post-bridge.ts

@@ -5,6 +5,7 @@ import type {
   ApprovalResolvedEvent,
   ChatMessageEvent,
   KapsoMessageEvent,
+  TaskBlockedEvent,
   TaskBudgetRefusedEvent,
   VcsEvent,
   VcsEventKind,
@@ -44,6 +45,11 @@ const onTaskCreated = observed("task.created", async (data) => {
     );
 });
 
+const onTaskBlocked = observed("task.create_blocked", async (data) => {
+  const { skipExtensionId, ...event } = data as TaskBlockedEvent & { skipExtensionId?: string };
+  await dispatchPost("post.task.blocked", event, { skipExtensionId });
+});
+
 const onTaskCompleted = observed("task.completed", async (data) => {
   const task = await taskFrom(data);
   if (!task) return;
@@ -358,6 +364,7 @@ export function initExtensionPostBridge(): void {
   if (subscribed) return;
   subscribed = true;
   workflowEventBus.on("task.created", onTaskCreated);
+  workflowEventBus.on("task.create_blocked", onTaskBlocked);
   workflowEventBus.on("task.completed", onTaskCompleted);
   workflowEventBus.on("task.failed", onTaskFailed);
   workflowEventBus.on("task.cancelled", onTaskCancelled);
@@ -377,6 +384,7 @@ export function teardownExtensionPostBridge(): void {
   if (!subscribed) return;
   subscribed = false;
   workflowEventBus.off("task.created", onTaskCreated);
+  workflowEventBus.off("task.create_blocked", onTaskBlocked);
   workflowEventBus.off("task.completed", onTaskCompleted);
   workflowEventBus.off("task.failed", onTaskFailed);
   workflowEventBus.off("task.cancelled", onTaskCancelled);

package/src/hooks/context-bound-note.ts

@@ -0,0 +1,196 @@
+import { renameSync, writeFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { renderContextBoundNote } from "../prompts/context-bound-note";
+
+/**
+ * One-time "keep this turn bounded" note for long worker sessions, on every
+ * harness.
+ *
+ * This module owns the threshold, the once-per-task claim and the rendering.
+ * A harness supplies only two things: the prompt size of its latest
+ * main-thread request (input + cache read + cache write tokens) and a way to
+ * put text in front of the model mid-session.
+ *
+ * - Claude: the session writes the size next to the task file
+ *   (`recordContextState`); the PostToolUse hook claims a marker file
+ *   (`claimContextBoundNote`) and returns the note as tool context.
+ * - In-process harnesses (codex, pi, opencode, amp, claude-managed): the session
+ *   feeds each request's size to `createContextBoundNote`, which injects the
+ *   note through the harness's own mid-turn input, and only while that input
+ *   still lands inside the current turn.
+ *
+ * Every failure path means "no note": nothing here throws into a session or
+ * blocks a tool call.
+ */
+
+/**
+ * Threshold from `CONTEXT_BOUND_NOTE_TOKENS`. Off by default: unset, empty,
+ * 0 or invalid returns 0 (off); a positive integer turns the note on at that
+ * many tokens.
+ */
+export function contextBoundNoteThreshold(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.CONTEXT_BOUND_NOTE_TOKENS?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return 0;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) ? parsed : 0;
+}
+
+/** True when a valid token count reaches an enabled (> 0) threshold. */
+function reachesThreshold(contextTokens: unknown, threshold: number): contextTokens is number {
+  return (
+    threshold > 0 &&
+    typeof contextTokens === "number" &&
+    Number.isFinite(contextTokens) &&
+    contextTokens >= threshold
+  );
+}
+
+/** Render the note and hand it to `inject`. Fails open. */
+async function deliverContextBoundNote(
+  contextTokens: number,
+  model: string | undefined,
+  inject: (note: string) => unknown,
+): Promise<void> {
+  try {
+    const note = await renderContextBoundNote(contextTokens, model);
+    if (note) await inject(note);
+  } catch {
+    // Fail open.
+  }
+}
+
+export function contextStatePath(taskFilePath: string): string {
+  return `${taskFilePath}.context.json`;
+}
+
+export function contextBoundNoteMarkerPath(taskFilePath: string): string {
+  return `${taskFilePath}.bound-note`;
+}
+
+/** What the session records for the hook: the latest request's size and the session's model. */
+export interface ContextState {
+  contextTokens: number;
+  model?: string;
+}
+
+/**
+ * Record the latest request's context size (and the session's model, for the
+ * window share) for the hook. Synchronous so
+ * writes land in stream order; tmp + rename so the hook never reads a partial
+ * file. Errors are swallowed: a missing state file only means no note.
+ */
+export function recordContextState(
+  taskFilePath: string,
+  contextTokens: number,
+  model?: string,
+): void {
+  const path = contextStatePath(taskFilePath);
+  const tmp = `${path}.tmp`;
+  try {
+    writeFileSync(
+      tmp,
+      JSON.stringify({ contextTokens, model, updatedAt: new Date().toISOString() }),
+    );
+    renameSync(tmp, path);
+  } catch {
+    // Fail open.
+  }
+}
+
+/**
+ * Returns the recorded state when the note should fire now, else null. Fires at
+ * most once per task file: the marker is created with `wx`, so a second call
+ * (or a concurrent hook) loses the race and gets null.
+ */
+export async function claimContextBoundNote(
+  taskFilePath: string | undefined,
+  threshold: number,
+): Promise<ContextState | null> {
+  if (!taskFilePath || threshold <= 0) return null;
+  let contextTokens: unknown;
+  let model: unknown;
+  try {
+    const state = JSON.parse(await readFile(contextStatePath(taskFilePath), "utf8")) as {
+      contextTokens?: unknown;
+      model?: unknown;
+    };
+    contextTokens = state?.contextTokens;
+    model = state?.model;
+  } catch {
+    return null;
+  }
+  if (!reachesThreshold(contextTokens, threshold)) return null;
+  try {
+    await writeFile(contextBoundNoteMarkerPath(taskFilePath), new Date().toISOString(), {
+      flag: "wx",
+    });
+  } catch {
+    return null;
+  }
+  return { contextTokens, model: typeof model === "string" && model ? model : undefined };
+}
+
+/** Claude PostToolUse path: claim from the task file, then hand the note to `inject`. */
+export async function injectClaimedContextBoundNote(
+  taskFilePath: string | undefined,
+  threshold: number,
+  inject: (note: string) => unknown,
+): Promise<void> {
+  const state = await claimContextBoundNote(taskFilePath, threshold).catch(() => null);
+  if (state) await deliverContextBoundNote(state.contextTokens, state.model, inject);
+}
+
+/**
+ * In-process path. Returns an observer the session calls with each
+ * main-thread request's prompt size. The first size at or above `threshold`
+ * claims the note for this session (one session runs one task) and renders
+ * it; later sizes are ignored. The returned promise never rejects.
+ *
+ * Rendering is async (HTTP on workers), so the session may have moved on by
+ * the time the note is ready. `canDeliver` decides then: true injects it;
+ * false holds it, and each later call retries the held note instead of
+ * rendering a new one. A session that settles, aborts or ends its last turn
+ * first never gets it.
+ */
+export function createContextBoundNote(options: {
+  threshold: number;
+  /** The session's model, read when the note renders, for the window share. */
+  model?: () => string | undefined;
+  inject: (note: string) => unknown;
+  /** True while a note injected now reaches the model inside the current turn. */
+  canDeliver: () => boolean;
+}): (contextTokens: number | undefined) => Promise<void> {
+  let state: "idle" | "rendering" | "held" | "done" = "idle";
+  let held = "";
+  const tryDeliver = async (note: string): Promise<void> => {
+    try {
+      if (!options.canDeliver()) {
+        held = note;
+        state = "held";
+        return;
+      }
+      state = "done";
+      await options.inject(note);
+    } catch {
+      // Fail open.
+    }
+  };
+  return async (contextTokens) => {
+    if (state === "held") return tryDeliver(held);
+    if (state !== "idle" || !reachesThreshold(contextTokens, options.threshold)) return;
+    state = "rendering";
+    let note = "";
+    try {
+      note = await renderContextBoundNote(contextTokens, options.model?.());
+    } catch {
+      // Fail open.
+    }
+    if (!note) {
+      state = "done";
+      return;
+    }
+    await tryDeliver(note);
+  };
+}

package/src/hooks/hook.ts

@@ -24,6 +24,7 @@ import { getMcpBaseUrl, MAX_PROFILE_FILE_LENGTH } from "../utils/constants";
 import { isSessionSummarySkipped } from "../utils/env-flag";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { contextBoundNoteThreshold, injectClaimedContextBoundNote } from "./context-bound-note";
 import { guardGhPrBody } from "./pr-body-guard";
 import { guardGhPrRoom } from "./pr-room-guard";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
@@ -78,6 +79,8 @@ interface HookMessage {
   tool_input?: Record<string, unknown>;
   tool_response?: Record<string, unknown>;
   tool_use_id?: string;
+  /** Set only when the hook fires inside a subagent. */
+  agent_id?: string;
   prompt?: string;
   stop_hook_active?: boolean;
 }
@@ -1339,6 +1342,15 @@ export async function handleHook(): Promise<void> {
               `Task sent successfully.${maybeTaskId ? ` Task ID: ${maybeTaskId}.` : ""} Monitor progress using the get-task-details tool periodically.`,
             );
           }
+        } else if (!msg.agent_id) {
+          // One-time nudge once the session's context crosses the threshold.
+          // Main thread only: a subagent call must not consume the marker.
+          // Any failure means no note; it never blocks the tool call.
+          await injectClaimedContextBoundNote(
+            process.env.TASK_FILE,
+            contextBoundNoteThreshold(),
+            (note) => outputToolContext("PostToolUse", note),
+          );
         }
       }
       break;

package/src/http/all-routes.ts

@@ -15,9 +15,11 @@ import "./apps";
 import "./assets";
 import "./budgets";
 import "./codex-oauth-device";
+import "./codex-oauth-accounts";
 import "./codex-oauth-keep-warm";
 import "./comb";
 import "./config";
+import "./pool-keys";
 import "./context";
 import "./core";
 import "./db-query";