@desplega.ai/agent-swarm 1.69.0 → 1.69.1

package/src/tasks/additive-buffer.ts

@@ -0,0 +1,152 @@
+/**
+ * Generic additive/debounce buffer, keyed on `contextKey` (or any string key).
+ *
+ * Phase 2 of cross-ingress sibling-task awareness — research §5.
+ *
+ * Extracted from `src/slack/thread-buffer.ts` so any ingress (AgentMail,
+ * GitHub/GitLab issue comments, Linear comments — NOT schedule/workflow) can
+ * coalesce rapid follow-up inputs into a single task.
+ *
+ * The primitive is a factory: each caller owns its own buffer registry with
+ * its own flush callback. That keeps flush semantics ingress-specific while
+ * the debounce / append / count plumbing is shared.
+ *
+ * Behavior:
+ *   - `enqueue(key, item)` appends `item` to the in-memory buffer for `key`.
+ *   - The debounce timer is reset on every append.
+ *   - When the timer fires, `onFlush(items, key, reason="timer")` is called
+ *     with the accumulated list.
+ *   - `instantFlush(key)` fires the callback immediately with
+ *     `reason="manual"` and clears the buffer.
+ *   - `cancel(key)` drops the buffer without flushing (used by ingress when
+ *     the underlying context becomes irrelevant — e.g. user cancels).
+ *
+ * Concurrency: single-process, single-event-loop. No cross-instance locking.
+ * Flush callbacks run sequentially per key (the buffer is cleared BEFORE the
+ * callback fires, so re-enqueues during `onFlush` create a fresh buffer).
+ */
+
+export type BufferFlushReason = "timer" | "manual";
+
+export interface AdditiveBufferOptions<T> {
+  /**
+   * Debounce timeout. Resets on every append. When it elapses without new
+   * appends, `onFlush` is called.
+   */
+  timeoutMs: number;
+  /**
+   * Called with the accumulated items when the buffer flushes. Receives the
+   * `contextKey` the buffer was created under and a `reason` indicating
+   * whether this was a timer-driven flush or a manual (`instantFlush`) one.
+   *
+   * Errors thrown here are caught and logged — they do NOT re-enter the
+   * buffer, because the buffer has already been cleared by the time `onFlush`
+   * is called. Callers that need retry semantics must implement them inside
+   * `onFlush`.
+   */
+  onFlush: (items: T[], contextKey: string, reason: BufferFlushReason) => void | Promise<void>;
+  /**
+   * Optional label, used in log lines (`[buffer:${label}]`). Helps when
+   * multiple buffers exist in the same process.
+   */
+  label?: string;
+}
+
+export interface AdditiveBuffer<T> {
+  /** Append an item, creating the buffer if needed. Resets the debounce timer. */
+  enqueue(contextKey: string, item: T): void;
+  /** True when a buffer exists for this key (i.e. at least one item is queued). */
+  isBuffered(contextKey: string): boolean;
+  /** Number of items currently queued for this key, or 0. */
+  count(contextKey: string): number;
+  /** Flush immediately with `reason="manual"`. No-op when no buffer exists. */
+  instantFlush(contextKey: string): Promise<void>;
+  /** Drop the buffer without flushing. No-op when no buffer exists. */
+  cancel(contextKey: string): boolean;
+  /** For tests / diagnostics. */
+  keys(): string[];
+}
+
+interface BufferEntry<T> {
+  items: T[];
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export function createAdditiveBuffer<T>(options: AdditiveBufferOptions<T>): AdditiveBuffer<T> {
+  const { timeoutMs, onFlush, label } = options;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`additive-buffer: timeoutMs must be a positive number, got ${timeoutMs}`);
+  }
+
+  const buffers = new Map<string, BufferEntry<T>>();
+  const prefix = label ? `[buffer:${label}]` : "[buffer]";
+
+  function scheduleFlush(key: string) {
+    return setTimeout(() => {
+      void doFlush(key, "timer");
+    }, timeoutMs);
+  }
+
+  async function doFlush(key: string, reason: BufferFlushReason): Promise<void> {
+    const entry = buffers.get(key);
+    if (!entry || entry.items.length === 0) {
+      buffers.delete(key);
+      return;
+    }
+    clearTimeout(entry.timer);
+    buffers.delete(key);
+    try {
+      await onFlush(entry.items, key, reason);
+    } catch (error) {
+      console.error(`${prefix} onFlush threw for key=${key}:`, error);
+    }
+  }
+
+  return {
+    enqueue(contextKey: string, item: T): void {
+      if (!contextKey) {
+        throw new Error("additive-buffer: contextKey is required");
+      }
+      const existing = buffers.get(contextKey);
+      if (existing) {
+        clearTimeout(existing.timer);
+        existing.items.push(item);
+        existing.timer = scheduleFlush(contextKey);
+        console.log(
+          `${prefix} append: ${contextKey} (${existing.items.length} items, timer reset to ${timeoutMs}ms)`,
+        );
+      } else {
+        const entry: BufferEntry<T> = {
+          items: [item],
+          timer: scheduleFlush(contextKey),
+        };
+        buffers.set(contextKey, entry);
+        console.log(`${prefix} created: ${contextKey} (timer set to ${timeoutMs}ms)`);
+      }
+    },
+
+    isBuffered(contextKey: string): boolean {
+      return buffers.has(contextKey);
+    },
+
+    count(contextKey: string): number {
+      return buffers.get(contextKey)?.items.length ?? 0;
+    },
+
+    instantFlush(contextKey: string): Promise<void> {
+      return doFlush(contextKey, "manual");
+    },
+
+    cancel(contextKey: string): boolean {
+      const entry = buffers.get(contextKey);
+      if (!entry) return false;
+      clearTimeout(entry.timer);
+      buffers.delete(contextKey);
+      return true;
+    },
+
+    keys(): string[] {
+      return Array.from(buffers.keys());
+    },
+  };
+}

package/src/tasks/additive-ingress.ts

@@ -0,0 +1,125 @@
+/**
+ * Generic "additive ingress" helper for Phase 2 cross-ingress sibling-awareness.
+ *
+ * Wraps `createAdditiveBuffer` with the typical pattern used by comment-style
+ * ingress points (AgentMail threads, GitHub/GitLab issue comments, Linear
+ * comments): when a sibling task is already in flight for the same contextKey,
+ * debounce rapid follow-up inputs into a SINGLE follow-up task instead of
+ * spawning N tasks.
+ *
+ * This generalizes the Slack `ADDITIVE_SLACK` buffer — Slack's own buffer stays
+ * as-is to preserve exact behaviour; other ingress points opt in via env flags.
+ *
+ * Default: opt-in (env flag unset => all calls are no-ops; caller proceeds to
+ * create a task normally).
+ */
+
+import { type AdditiveBuffer, createAdditiveBuffer } from "./additive-buffer";
+
+export type IngressFlushReason = "timer" | "manual";
+
+export interface IngressBufferItem<T> {
+  payload: T;
+  enqueuedAt: number;
+}
+
+export interface IngressBufferOptions<T> {
+  /** Short identifier used in logs, e.g. "agentmail", "github-issue-comment". */
+  source: string;
+  /**
+   * Env flag name (e.g. `"ADDITIVE_AGENTMAIL"`). When the flag resolves to
+   * `"true"` the buffer is enabled; otherwise `maybeBuffer()` is a no-op.
+   */
+  envFlag: string;
+  /** Debounce timeout in ms. Reset on every enqueue. Default: 10000ms. */
+  timeoutMs?: number;
+  /**
+   * Called when the buffer flushes (timer expiry OR manual). Receives the
+   * payloads in arrival order, the contextKey, and the reason. Errors thrown
+   * here are logged and swallowed.
+   */
+  onFlush: (items: T[], contextKey: string, reason: IngressFlushReason) => Promise<void> | void;
+}
+
+export interface IngressBuffer<T> {
+  /**
+   * `true` when the env flag was set to `"true"` at construction time.
+   * Callers should still guard with `maybeBuffer` — this is informational.
+   */
+  enabled: boolean;
+  /**
+   * Attempt to buffer an input. Returns `true` when the item was buffered
+   * (caller MUST NOT create a task), `false` otherwise (caller proceeds).
+   *
+   * Params:
+   *   - `contextKey`  — uniform sibling key from Phase 1. Empty string disables.
+   *   - `siblingInFlight` — whether the caller already knows a sibling exists
+   *     for `contextKey`. Callers typically pass the boolean from
+   *     `getInProgressTasksByContextKey(contextKey).length > 0`.
+   *   - `payload` — the item to buffer.
+   */
+  maybeBuffer(contextKey: string, siblingInFlight: boolean, payload: T): boolean;
+  /** True if the key currently has a pending buffer (for debugging/tests). */
+  isBuffered(contextKey: string): boolean;
+  /** Count of items in the buffer for `contextKey`. */
+  count(contextKey: string): number;
+  /** Flush immediately, cancelling the debounce timer. */
+  instantFlush(contextKey: string): Promise<void>;
+  /** Drop buffered items without flushing. */
+  cancel(contextKey: string): void;
+  /** Raw underlying buffer — escape hatch for tests. */
+  _buffer: AdditiveBuffer<T>;
+}
+
+/**
+ * Read the env flag value lazily so tests can toggle it without re-importing.
+ */
+function envEnabled(flag: string): boolean {
+  return process.env[flag] === "true";
+}
+
+/**
+ * Create an ingress buffer. The wrapper records the env flag at construction
+ * time (not per-call) so behaviour is stable across a process run.
+ *
+ * Consumers typically:
+ *   1. Look up siblings for the contextKey (`getInProgressTasksByContextKey`).
+ *   2. Call `buffer.maybeBuffer(contextKey, siblings.length > 0, payload)`.
+ *   3. If `true`, stop — buffered. Otherwise, proceed to `createTaskWithSiblingAwareness`.
+ */
+export function createIngressBuffer<T>(opts: IngressBufferOptions<T>): IngressBuffer<T> {
+  const enabled = envEnabled(opts.envFlag);
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+
+  const buffer = createAdditiveBuffer<T>({
+    timeoutMs,
+    label: opts.source,
+    onFlush: async (items, key, reason) => {
+      await opts.onFlush(items, key, reason);
+    },
+  });
+
+  return {
+    enabled,
+    maybeBuffer(contextKey, siblingInFlight, payload) {
+      if (!enabled) return false;
+      if (!contextKey) return false;
+      if (!siblingInFlight) return false;
+      buffer.enqueue(contextKey, payload);
+      return true;
+    },
+    isBuffered(contextKey) {
+      return buffer.isBuffered(contextKey);
+    },
+    count(contextKey) {
+      return buffer.count(contextKey);
+    },
+    instantFlush(contextKey) {
+      return buffer.instantFlush(contextKey);
+    },
+    cancel(contextKey) {
+      buffer.cancel(contextKey);
+    },
+    _buffer: buffer,
+  };
+}

package/src/tasks/context-key.ts

@@ -0,0 +1,245 @@
+/**
+ * Cross-ingress task context keys.
+ *
+ * Every ingress surface (Slack, GitHub, GitLab, AgentMail, Linear, schedules,
+ * workflows, ...) builds a uniform string key that identifies the "context entity"
+ * a task belongs to. We persist the key on `agent_tasks.contextKey` so that a
+ * single indexed lookup can return all sibling tasks for a given entity.
+ *
+ * Key schema:
+ *   task:slack:{channelId}:{threadTs}
+ *   task:agentmail:{threadId}
+ *   task:trackers:github:{owner}:{repo}:{issue|pr}:{number}
+ *   task:trackers:gitlab:{projectId}:{mr|issue}:{iid}
+ *   task:trackers:linear:{issueIdentifier}        (e.g. DES-42 — case preserved)
+ *   task:schedule:{scheduleId}
+ *   task:workflow:{workflowRunId}
+ *
+ * Rules:
+ *   - Fixed prefix tokens (`task`, family, sub-family, kind) are always lowercase.
+ *   - Case is preserved inside identifier portions so Linear identifiers and
+ *     GitHub repo slugs round-trip exactly.
+ *   - `:` is the separator and forbidden in any embedded value. Callers must
+ *     sanitize first; unsanitized inputs throw so bugs surface loudly at the
+ *     ingress boundary rather than creating silent mis-keyed tasks.
+ *   - `null`/`undefined`/empty values throw — a context key either exists
+ *     fully or not at all.
+ */
+
+const SEPARATOR = ":";
+
+export type ContextKeyFamily = "slack" | "agentmail" | "trackers" | "schedule" | "workflow";
+
+export type TrackerProvider = "github" | "gitlab" | "linear";
+
+export type ParsedContextKey =
+  | { family: "slack"; parts: { channelId: string; threadTs: string } }
+  | { family: "agentmail"; parts: { threadId: string } }
+  | {
+      family: "trackers";
+      subFamily: "github";
+      parts: { owner: string; repo: string; kind: "issue" | "pr"; number: number };
+    }
+  | {
+      family: "trackers";
+      subFamily: "gitlab";
+      parts: { projectId: string; kind: "mr" | "issue"; iid: number };
+    }
+  | {
+      family: "trackers";
+      subFamily: "linear";
+      parts: { issueIdentifier: string };
+    }
+  | { family: "schedule"; parts: { scheduleId: string } }
+  | { family: "workflow"; parts: { workflowRunId: string } };
+
+function assertSafePart(value: unknown, label: string): string {
+  if (value === null || value === undefined) {
+    throw new Error(`context-key: "${label}" is required`);
+  }
+  const str = typeof value === "string" ? value : String(value);
+  if (str.length === 0) {
+    throw new Error(`context-key: "${label}" must be non-empty`);
+  }
+  if (str.includes(SEPARATOR)) {
+    throw new Error(
+      `context-key: "${label}" must not contain "${SEPARATOR}"; caller must sanitize (got ${JSON.stringify(str)})`,
+    );
+  }
+  return str;
+}
+
+export function slackContextKey(input: { channelId: string; threadTs: string }): string {
+  const channelId = assertSafePart(input.channelId, "channelId");
+  const threadTs = assertSafePart(input.threadTs, "threadTs");
+  return ["task", "slack", channelId, threadTs].join(SEPARATOR);
+}
+
+export function agentmailContextKey(input: { threadId: string }): string {
+  const threadId = assertSafePart(input.threadId, "threadId");
+  return ["task", "agentmail", threadId].join(SEPARATOR);
+}
+
+export function githubContextKey(input: {
+  owner: string;
+  repo: string;
+  kind: "issue" | "pr";
+  number: number;
+}): string {
+  const owner = assertSafePart(input.owner, "owner");
+  const repo = assertSafePart(input.repo, "repo");
+  const kind = assertSafePart(input.kind, "kind").toLowerCase();
+  if (kind !== "issue" && kind !== "pr") {
+    throw new Error(
+      `context-key: github "kind" must be "issue" or "pr" (got ${JSON.stringify(kind)})`,
+    );
+  }
+  const number = assertSafePart(input.number, "number");
+  if (!/^\d+$/.test(number)) {
+    throw new Error(
+      `context-key: github "number" must be a positive integer (got ${JSON.stringify(number)})`,
+    );
+  }
+  return ["task", "trackers", "github", owner, repo, kind, number].join(SEPARATOR);
+}
+
+export function gitlabContextKey(input: {
+  projectId: string | number;
+  kind: "mr" | "issue";
+  iid: number;
+}): string {
+  const projectId = assertSafePart(input.projectId, "projectId");
+  const kind = assertSafePart(input.kind, "kind").toLowerCase();
+  if (kind !== "mr" && kind !== "issue") {
+    throw new Error(
+      `context-key: gitlab "kind" must be "mr" or "issue" (got ${JSON.stringify(kind)})`,
+    );
+  }
+  const iid = assertSafePart(input.iid, "iid");
+  if (!/^\d+$/.test(iid)) {
+    throw new Error(
+      `context-key: gitlab "iid" must be a positive integer (got ${JSON.stringify(iid)})`,
+    );
+  }
+  return ["task", "trackers", "gitlab", projectId, kind, iid].join(SEPARATOR);
+}
+
+export function linearContextKey(input: { issueIdentifier: string }): string {
+  const issueIdentifier = assertSafePart(input.issueIdentifier, "issueIdentifier");
+  return ["task", "trackers", "linear", issueIdentifier].join(SEPARATOR);
+}
+
+export function scheduleContextKey(input: { scheduleId: string }): string {
+  const scheduleId = assertSafePart(input.scheduleId, "scheduleId");
+  return ["task", "schedule", scheduleId].join(SEPARATOR);
+}
+
+export function workflowContextKey(input: { workflowRunId: string }): string {
+  const workflowRunId = assertSafePart(input.workflowRunId, "workflowRunId");
+  return ["task", "workflow", workflowRunId].join(SEPARATOR);
+}
+
+/**
+ * Parse a context key back into a structured form. Throws on malformed input.
+ * Useful for diagnostics and downstream routing; not used on the hot insert path.
+ */
+export function parseContextKey(key: string): ParsedContextKey {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new Error("context-key: key must be a non-empty string");
+  }
+  const parts = key.split(SEPARATOR);
+  if (parts.length < 3 || parts[0] !== "task") {
+    throw new Error(`context-key: malformed key (expected "task:..."): ${JSON.stringify(key)}`);
+  }
+  const family = parts[1];
+  switch (family) {
+    case "slack": {
+      if (parts.length !== 4) {
+        throw new Error(`context-key: malformed slack key: ${JSON.stringify(key)}`);
+      }
+      return {
+        family: "slack",
+        parts: { channelId: parts[2] as string, threadTs: parts[3] as string },
+      };
+    }
+    case "agentmail": {
+      if (parts.length !== 3) {
+        throw new Error(`context-key: malformed agentmail key: ${JSON.stringify(key)}`);
+      }
+      return { family: "agentmail", parts: { threadId: parts[2] as string } };
+    }
+    case "schedule": {
+      if (parts.length !== 3) {
+        throw new Error(`context-key: malformed schedule key: ${JSON.stringify(key)}`);
+      }
+      return { family: "schedule", parts: { scheduleId: parts[2] as string } };
+    }
+    case "workflow": {
+      if (parts.length !== 3) {
+        throw new Error(`context-key: malformed workflow key: ${JSON.stringify(key)}`);
+      }
+      return { family: "workflow", parts: { workflowRunId: parts[2] as string } };
+    }
+    case "trackers": {
+      const subFamily = parts[2];
+      if (subFamily === "github") {
+        if (parts.length !== 7) {
+          throw new Error(`context-key: malformed github key: ${JSON.stringify(key)}`);
+        }
+        const owner = parts[3] as string;
+        const repo = parts[4] as string;
+        const kind = parts[5];
+        const numberStr = parts[6] as string;
+        if (kind !== "issue" && kind !== "pr") {
+          throw new Error(`context-key: malformed github kind "${kind}": ${JSON.stringify(key)}`);
+        }
+        const number = Number.parseInt(numberStr, 10);
+        if (!Number.isFinite(number)) {
+          throw new Error(
+            `context-key: malformed github number "${numberStr}": ${JSON.stringify(key)}`,
+          );
+        }
+        return {
+          family: "trackers",
+          subFamily: "github",
+          parts: { owner, repo, kind, number },
+        };
+      }
+      if (subFamily === "gitlab") {
+        if (parts.length !== 6) {
+          throw new Error(`context-key: malformed gitlab key: ${JSON.stringify(key)}`);
+        }
+        const projectId = parts[3] as string;
+        const kind = parts[4];
+        const iidStr = parts[5] as string;
+        if (kind !== "mr" && kind !== "issue") {
+          throw new Error(`context-key: malformed gitlab kind "${kind}": ${JSON.stringify(key)}`);
+        }
+        const iid = Number.parseInt(iidStr, 10);
+        if (!Number.isFinite(iid)) {
+          throw new Error(`context-key: malformed gitlab iid "${iidStr}": ${JSON.stringify(key)}`);
+        }
+        return {
+          family: "trackers",
+          subFamily: "gitlab",
+          parts: { projectId, kind, iid },
+        };
+      }
+      if (subFamily === "linear") {
+        if (parts.length !== 4) {
+          throw new Error(`context-key: malformed linear key: ${JSON.stringify(key)}`);
+        }
+        return {
+          family: "trackers",
+          subFamily: "linear",
+          parts: { issueIdentifier: parts[3] as string },
+        };
+      }
+      throw new Error(
+        `context-key: unknown trackers sub-family "${subFamily}": ${JSON.stringify(key)}`,
+      );
+    }
+    default:
+      throw new Error(`context-key: unknown family "${family}": ${JSON.stringify(key)}`);
+  }
+}

package/src/tasks/sibling-awareness.ts

@@ -0,0 +1,144 @@
+/**
+ * DB-backed orchestrator for cross-ingress sibling-task awareness (Phase 2).
+ *
+ * Wraps the pure renderer/picker in `sibling-block.ts` with a single round-trip
+ * to the DB so any ingress can call ONE function before `createTaskExtended`
+ * to (a) prepend the sibling block to the task description and (b) auto-wire
+ * `parentTaskId` for same-agent resume.
+ *
+ * Lives on the server side — safe to import from any of `src/slack/`,
+ * `src/github/`, `src/gitlab/`, `src/agentmail/`, `src/linear/`,
+ * `src/scheduler/`, `src/http/`, `src/tools/`. Workers don't call this.
+ */
+
+import {
+  type CreateTaskOptions,
+  createTaskExtended,
+  getAgentById,
+  getInProgressTasksByContextKey,
+} from "../be/db";
+import type { AgentTask } from "../types";
+import {
+  pickResumeParent,
+  prependSiblingBlock,
+  type SiblingTaskInfo,
+  stripSiblingBlock,
+} from "./sibling-block";
+
+export type ApplySiblingAwarenessInput = {
+  description: string;
+  contextKey: string;
+  // The agent that will own the new task. When provided, sibling auto-wiring
+  // for `parentTaskId` only fires if a sibling on the same agent exists.
+  // When null/undefined, no parent is wired (resume semantics undefined).
+  currentAgentId?: string | null;
+  // Optional override for "now" — used by tests for deterministic output.
+  now?: number;
+};
+
+export type ApplySiblingAwarenessResult = {
+  // The description with the sibling block prepended (or unchanged if no
+  // siblings were found).
+  description: string;
+  // The id of the sibling that should be wired as `parentTaskId`, or
+  // undefined when no eligible sibling exists. Callers MUST pass this through
+  // to `createTaskExtended` to get session resume.
+  parentTaskId?: string;
+  // The siblings the orchestrator considered. Useful for callers that want to
+  // log / instrument; safe to ignore.
+  siblings: SiblingTaskInfo[];
+};
+
+function toSiblingTaskInfo(task: AgentTask): SiblingTaskInfo {
+  const agent = task.agentId ? getAgentById(task.agentId) : null;
+  return {
+    id: task.id,
+    status: task.status,
+    agentId: task.agentId,
+    agentName: agent?.name ?? null,
+    description: stripSiblingBlock(task.task),
+    updatedAt: task.lastUpdatedAt,
+  };
+}
+
+/**
+ * Look up siblings for a given contextKey, render the prompt block, and
+ * return the (potentially) modified description plus the parent task id to
+ * wire. Safe to call when no siblings exist — returns the description
+ * unchanged and `parentTaskId: undefined`.
+ *
+ * Callers should NOT pass `parentTaskId` to `createTaskExtended` separately —
+ * the returned value already takes precedence. (If both are passed, callers
+ * are responsible for deciding which one wins.)
+ */
+export function applySiblingAwareness(
+  input: ApplySiblingAwarenessInput,
+): ApplySiblingAwarenessResult {
+  const { description, contextKey, currentAgentId } = input;
+  if (!contextKey) {
+    return { description, siblings: [] };
+  }
+
+  const tasks = getInProgressTasksByContextKey(contextKey);
+  if (tasks.length === 0) {
+    return { description, siblings: [] };
+  }
+
+  const siblings = tasks.map(toSiblingTaskInfo);
+  const parent = pickResumeParent(siblings, currentAgentId ?? null);
+  const newDescription = prependSiblingBlock(description, contextKey, siblings, input.now);
+
+  return {
+    description: newDescription,
+    parentTaskId: parent?.id,
+    siblings,
+  };
+}
+
+/**
+ * Convenience wrapper that applies sibling-awareness to a `(description,
+ * options)` pair ready to be passed to `createTaskExtended`.
+ *
+ * Semantics:
+ *   - `contextKey` is read from `options.contextKey` — callers must set it
+ *     before calling this helper (Phase 1 already does that at every ingress).
+ *   - If `options.parentTaskId` is already set, it is respected and NOT
+ *     overridden by sibling-awareness. This means any ingress that has its
+ *     own parent-picking logic (e.g. Slack lead handler) keeps working.
+ *   - The returned `options` object is a shallow copy; callers may pass it
+ *     directly to `createTaskExtended`.
+ */
+export function withSiblingAwareness(
+  description: string,
+  options: CreateTaskOptions,
+): { description: string; options: CreateTaskOptions } {
+  const contextKey = options.contextKey;
+  if (!contextKey) {
+    return { description, options };
+  }
+  const result = applySiblingAwareness({
+    description,
+    contextKey,
+    currentAgentId: options.agentId ?? null,
+  });
+  return {
+    description: result.description,
+    options: {
+      ...options,
+      parentTaskId: options.parentTaskId ?? result.parentTaskId,
+    },
+  };
+}
+
+/**
+ * Drop-in replacement for `createTaskExtended` that applies sibling-awareness
+ * first. Use this from every ingress that has a `contextKey` so cross-ingress
+ * sibling coordination is uniform without duplicating the wrapper boilerplate.
+ */
+export function createTaskWithSiblingAwareness(
+  description: string,
+  options: CreateTaskOptions,
+): AgentTask {
+  const { description: d, options: o } = withSiblingAwareness(description, options);
+  return createTaskExtended(d, o);
+}