@desplega.ai/agent-swarm 1.69.0 → 1.70.0

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);
+}

package/src/tasks/sibling-block.ts

@@ -0,0 +1,164 @@
+/**
+ * Pure rendering + selection helpers for cross-ingress sibling-task awareness.
+ *
+ * Phase 2 of the cross-ingress sibling-task awareness initiative. The reader
+ * side: when an ingress is about to create a task and other tasks already
+ * share the same `contextKey`, we (a) prepend a `<sibling_tasks_in_progress>`
+ * block to the new task's description so the worker knows about the
+ * concurrent work, and (b) optionally wire `parentTaskId` to the most
+ * relevant sibling so Claude-Code session resume kicks in.
+ *
+ * This module is intentionally dependency-free — no DB calls, no I/O — so it
+ * is trivial to unit-test and safe to call from any ingress.
+ */
+
+export type SiblingTaskInfo = {
+  id: string;
+  status: string;
+  agentId: string | null;
+  agentName: string | null;
+  description: string;
+  // Most recent change timestamp (ISO string). Used for relative-time render
+  // and for picking the "best" sibling to wire as parent.
+  updatedAt: string;
+};
+
+const DESCRIPTION_TRUNCATE = 200;
+
+// Status priority for picking the resume parent. Higher number wins.
+// in_progress > pending > offered > paused (per task spec, research §3.2).
+const STATUS_PRIORITY: Record<string, number> = {
+  in_progress: 4,
+  pending: 3,
+  offered: 2,
+  paused: 1,
+};
+
+/**
+ * Remove a previously-prepended sibling block (if any) from a task
+ * description. Called before rendering a sibling into a *new* block so we
+ * don't end up nesting blocks recursively — siblings show their ORIGINAL
+ * user-facing intent, not the inherited sibling-awareness preamble from when
+ * they were created.
+ */
+export function stripSiblingBlock(description: string): string {
+  if (typeof description !== "string") return "";
+  const start = description.indexOf("<sibling_tasks_in_progress>");
+  if (start === -1) return description;
+  const closeTag = "</sibling_tasks_in_progress>";
+  const end = description.indexOf(closeTag, start);
+  if (end === -1) return description;
+  // Drop block + any immediately following whitespace (blank line separator).
+  const after = description.slice(end + closeTag.length).replace(/^\s+/, "");
+  const before = description.slice(0, start).replace(/\s+$/, "");
+  return before ? `${before}\n\n${after}` : after;
+}
+
+export function truncateForBlock(s: string, max: number = DESCRIPTION_TRUNCATE): string {
+  if (typeof s !== "string") return "";
+  // Collapse any embedded newlines so each sibling stays on one rendered line
+  // (the description follows the bullet on its own continuation line).
+  const flattened = s.replace(/\s+/g, " ").trim();
+  if (flattened.length <= max) return flattened;
+  return `${flattened.slice(0, max).trimEnd()}…`;
+}
+
+export function formatRelativeTime(then: string | number | Date, now: number = Date.now()): string {
+  const t = then instanceof Date ? then.getTime() : new Date(then).getTime();
+  if (!Number.isFinite(t)) return "unknown time";
+  const diffMs = Math.max(0, now - t);
+  const sec = Math.floor(diffMs / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h`;
+  const day = Math.floor(hr / 24);
+  return `${day}d`;
+}
+
+/**
+ * Render the sibling-tasks block. Returns "" when there are no siblings so
+ * callers can unconditionally prepend the result.
+ */
+export function renderSiblingBlock(
+  contextKey: string,
+  siblings: SiblingTaskInfo[],
+  now: number = Date.now(),
+): string {
+  if (!siblings || siblings.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push("<sibling_tasks_in_progress>");
+  lines.push(
+    `The following tasks are already running in the same context (contextKey: ${contextKey}). The user has submitted new input while they were in flight — coordinate with them, do not duplicate:`,
+  );
+  lines.push("");
+  for (const s of siblings) {
+    const agentLabel = s.agentName
+      ? `agent:${s.agentName}`
+      : s.agentId
+        ? `agent:${s.agentId}`
+        : "agent:unassigned";
+    const rel = formatRelativeTime(s.updatedAt, now);
+    lines.push(`- [${s.status}] task:${s.id} — ${agentLabel} — started ${rel} ago`);
+    lines.push(`  "${truncateForBlock(s.description)}"`);
+  }
+  lines.push("</sibling_tasks_in_progress>");
+  return lines.join("\n");
+}
+
+/**
+ * Pick the sibling that should be wired as `parentTaskId` so Claude-Code
+ * session resume picks up the conversation. Returns `null` when no sibling
+ * is eligible.
+ *
+ * Eligibility rules (research §3.2 + task spec):
+ *   - Sibling must be assigned to the same agent as the incoming task.
+ *     Cross-agent resume doesn't make sense — different worker, different
+ *     filesystem, different session state.
+ *   - Among eligible siblings, prefer higher status priority
+ *     (in_progress > pending > offered > paused), then most-recently-updated.
+ *
+ * If `currentAgentId` is null/undefined, no wiring happens — we don't know
+ * which worker will pick up the task, so resume semantics are undefined.
+ */
+export function pickResumeParent<
+  T extends Pick<SiblingTaskInfo, "id" | "status" | "agentId" | "updatedAt">,
+>(siblings: T[], currentAgentId: string | null | undefined): T | null {
+  if (!currentAgentId) return null;
+  if (!siblings || siblings.length === 0) return null;
+
+  const eligible = siblings.filter((s) => s.agentId && s.agentId === currentAgentId);
+  if (eligible.length === 0) return null;
+
+  let best: T | null = null;
+  let bestPriority = -1;
+  let bestTime = -1;
+  for (const s of eligible) {
+    const priority = STATUS_PRIORITY[s.status] ?? 0;
+    const time = new Date(s.updatedAt).getTime();
+    const timeFinite = Number.isFinite(time) ? time : 0;
+    if (priority > bestPriority || (priority === bestPriority && timeFinite > bestTime)) {
+      best = s;
+      bestPriority = priority;
+      bestTime = timeFinite;
+    }
+  }
+  return best;
+}
+
+/**
+ * Convenience: prepend the sibling block to a task description, with a blank
+ * line separator. Returns `description` unchanged when there are no siblings.
+ */
+export function prependSiblingBlock(
+  description: string,
+  contextKey: string,
+  siblings: SiblingTaskInfo[],
+  now: number = Date.now(),
+): string {
+  const block = renderSiblingBlock(contextKey, siblings, now);
+  if (!block) return description;
+  return `${block}\n\n${description}`;
+}