@desplega.ai/agent-swarm 1.69.0 → 1.69.1

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

package/src/tests/additive-buffer.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, test } from "bun:test";
+import { createAdditiveBuffer } from "../tasks/additive-buffer";
+
+/**
+ * Helper: wait for a timer-based flush. We use tight timeouts (10-30ms) so
+ * tests stay fast — these operate on Bun's event loop, not real time.
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+describe("createAdditiveBuffer", () => {
+  test("rejects non-positive timeoutMs", () => {
+    expect(() => createAdditiveBuffer({ timeoutMs: 0, onFlush: () => {} })).toThrow(
+      /positive number/,
+    );
+    expect(() => createAdditiveBuffer({ timeoutMs: -1, onFlush: () => {} })).toThrow();
+    // biome-ignore lint/suspicious/noExplicitAny: type-guard test
+    expect(() => createAdditiveBuffer({ timeoutMs: NaN as any, onFlush: () => {} })).toThrow();
+  });
+
+  test("enqueue without existing buffer creates one with timer", () => {
+    let flushed: number[] | null = null;
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 10_000,
+      onFlush: (items) => {
+        flushed = [...items];
+      },
+    });
+    buf.enqueue("k1", 1);
+    expect(buf.isBuffered("k1")).toBe(true);
+    expect(buf.count("k1")).toBe(1);
+    expect(flushed).toBeNull();
+    buf.cancel("k1");
+  });
+
+  test("three rapid enqueues coalesce into one flush", async () => {
+    const flushes: string[][] = [];
+    const buf = createAdditiveBuffer<string>({
+      timeoutMs: 20,
+      onFlush: (items) => {
+        flushes.push([...items]);
+      },
+      label: "test-coalesce",
+    });
+
+    buf.enqueue("k", "a");
+    await sleep(5);
+    buf.enqueue("k", "b");
+    await sleep(5);
+    buf.enqueue("k", "c");
+    expect(buf.count("k")).toBe(3);
+
+    // Wait for debounce to elapse
+    await sleep(50);
+
+    expect(flushes.length).toBe(1);
+    expect(flushes[0]).toEqual(["a", "b", "c"]);
+    expect(buf.isBuffered("k")).toBe(false);
+  });
+
+  test("enqueue resets the timer", async () => {
+    const flushes: number[][] = [];
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 30,
+      onFlush: (items) => {
+        flushes.push([...items]);
+      },
+    });
+
+    buf.enqueue("k", 1);
+    await sleep(20); // 20 < 30, timer would have NOT fired
+    buf.enqueue("k", 2); // resets
+    await sleep(20); // another 20 < 30
+    buf.enqueue("k", 3); // resets again
+
+    expect(flushes.length).toBe(0);
+    await sleep(60);
+    expect(flushes.length).toBe(1);
+    expect(flushes[0]).toEqual([1, 2, 3]);
+  });
+
+  test("instantFlush fires immediately with reason='manual'", async () => {
+    let seenReason: string | null = null;
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 10_000,
+      onFlush: (_items, _key, reason) => {
+        seenReason = reason;
+      },
+    });
+    buf.enqueue("k", 1);
+    await buf.instantFlush("k");
+    expect(seenReason).toBe("manual");
+    expect(buf.isBuffered("k")).toBe(false);
+  });
+
+  test("timer flush reports reason='timer'", async () => {
+    let seenReason: string | null = null;
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 10,
+      onFlush: (_items, _key, reason) => {
+        seenReason = reason;
+      },
+    });
+    buf.enqueue("k", 1);
+    await sleep(40);
+    expect(seenReason).toBe("timer");
+  });
+
+  test("instantFlush on unknown key is a no-op", async () => {
+    let called = false;
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 10_000,
+      onFlush: () => {
+        called = true;
+      },
+    });
+    await buf.instantFlush("nope");
+    expect(called).toBe(false);
+  });
+
+  test("cancel drops the buffer without flushing", async () => {
+    let called = false;
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 20,
+      onFlush: () => {
+        called = true;
+      },
+    });
+    buf.enqueue("k", 1);
+    expect(buf.cancel("k")).toBe(true);
+    expect(buf.isBuffered("k")).toBe(false);
+    await sleep(50);
+    expect(called).toBe(false);
+  });
+
+  test("cancel on unknown key returns false", () => {
+    const buf = createAdditiveBuffer<number>({ timeoutMs: 10_000, onFlush: () => {} });
+    expect(buf.cancel("nope")).toBe(false);
+  });
+
+  test("enqueue rejects empty contextKey", () => {
+    const buf = createAdditiveBuffer<number>({ timeoutMs: 10_000, onFlush: () => {} });
+    expect(() => buf.enqueue("", 1)).toThrow(/contextKey/);
+  });
+
+  test("onFlush errors are swallowed (logged, buffer still clears)", async () => {
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 10,
+      onFlush: () => {
+        throw new Error("boom");
+      },
+    });
+    buf.enqueue("k", 1);
+    await sleep(40);
+    expect(buf.isBuffered("k")).toBe(false);
+  });
+
+  test("buffers are independent across keys", async () => {
+    const flushes: Record<string, number[][]> = {};
+    const buf = createAdditiveBuffer<number>({
+      timeoutMs: 20,
+      onFlush: (items, key) => {
+        const arr = flushes[key] ?? [];
+        arr.push([...items]);
+        flushes[key] = arr;
+      },
+    });
+    buf.enqueue("a", 1);
+    buf.enqueue("b", 10);
+    buf.enqueue("a", 2);
+    await sleep(50);
+    expect(flushes.a).toEqual([[1, 2]]);
+    expect(flushes.b).toEqual([[10]]);
+  });
+
+  test("keys() returns active buffer keys", () => {
+    const buf = createAdditiveBuffer<number>({ timeoutMs: 10_000, onFlush: () => {} });
+    buf.enqueue("a", 1);
+    buf.enqueue("b", 2);
+    expect(new Set(buf.keys())).toEqual(new Set(["a", "b"]));
+    buf.cancel("a");
+    expect(buf.keys()).toEqual(["b"]);
+    buf.cancel("b");
+  });
+});

package/src/tests/additive-ingress.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createIngressBuffer } from "../tasks/additive-ingress";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+const FLAG = "TEST_ADDITIVE_INGRESS";
+
+describe("createIngressBuffer", () => {
+  beforeEach(() => {
+    process.env[FLAG] = "true";
+  });
+  afterEach(() => {
+    process.env[FLAG] = undefined;
+  });
+
+  test("env flag off → maybeBuffer always returns false", () => {
+    process.env[FLAG] = "false";
+    const flushes: string[][] = [];
+    const ib = createIngressBuffer<string>({
+      source: "test",
+      envFlag: FLAG,
+      timeoutMs: 20,
+      onFlush: (items) => {
+        flushes.push([...items]);
+      },
+    });
+    expect(ib.enabled).toBe(false);
+    expect(ib.maybeBuffer("ctx", true, "a")).toBe(false);
+    expect(ib.isBuffered("ctx")).toBe(false);
+  });
+
+  test("no sibling in flight → maybeBuffer returns false", () => {
+    const ib = createIngressBuffer<string>({
+      source: "test",
+      envFlag: FLAG,
+      timeoutMs: 20,
+      onFlush: () => {},
+    });
+    expect(ib.enabled).toBe(true);
+    expect(ib.maybeBuffer("ctx", false, "a")).toBe(false);
+  });
+
+  test("empty contextKey → maybeBuffer returns false", () => {
+    const ib = createIngressBuffer<string>({
+      source: "test",
+      envFlag: FLAG,
+      timeoutMs: 20,
+      onFlush: () => {},
+    });
+    expect(ib.maybeBuffer("", true, "a")).toBe(false);
+  });
+
+  test("enabled + sibling in flight + contextKey → buffers", async () => {
+    const flushes: Array<{ items: string[]; key: string; reason: string }> = [];
+    const ib = createIngressBuffer<string>({
+      source: "test",
+      envFlag: FLAG,
+      timeoutMs: 20,
+      onFlush: (items, key, reason) => {
+        flushes.push({ items: [...items], key, reason });
+      },
+    });
+    expect(ib.maybeBuffer("ctx", true, "one")).toBe(true);
+    expect(ib.maybeBuffer("ctx", true, "two")).toBe(true);
+    expect(ib.maybeBuffer("ctx", true, "three")).toBe(true);
+    expect(ib.count("ctx")).toBe(3);
+
+    await sleep(80);
+    expect(flushes.length).toBe(1);
+    expect(flushes[0]?.items).toEqual(["one", "two", "three"]);
+    expect(flushes[0]?.key).toBe("ctx");
+    expect(flushes[0]?.reason).toBe("timer");
+  });
+
+  test("instantFlush resolves immediately with reason=manual", async () => {
+    const flushes: Array<{ items: string[]; reason: string }> = [];
+    const ib = createIngressBuffer<string>({
+      source: "test",
+      envFlag: FLAG,
+      timeoutMs: 5000, // long
+      onFlush: (items, _key, reason) => {
+        flushes.push({ items: [...items], reason });
+      },
+    });
+    ib.maybeBuffer("k", true, "x");
+    ib.maybeBuffer("k", true, "y");
+    await ib.instantFlush("k");
+    expect(flushes.length).toBe(1);
+    expect(flushes[0]?.items).toEqual(["x", "y"]);
+    expect(flushes[0]?.reason).toBe("manual");
+  });
+
+  test("cancel drops items without flushing", async () => {
+    const flushes: string[][] = [];
+    const ib = createIngressBuffer<string>({
+      source: "test",
+      envFlag: FLAG,
+      timeoutMs: 20,
+      onFlush: (items) => {
+        flushes.push([...items]);
+      },
+    });
+    ib.maybeBuffer("k", true, "a");
+    ib.cancel("k");
+    await sleep(50);
+    expect(flushes.length).toBe(0);
+    expect(ib.isBuffered("k")).toBe(false);
+  });
+});

package/src/tests/context-key-db.test.ts

@@ -0,0 +1,87 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlinkSync } from "node:fs";
+import {
+  closeDb,
+  completeTask,
+  createAgent,
+  createTaskExtended,
+  getInProgressTasksByContextKey,
+  initDb,
+} from "../be/db";
+import { slackContextKey } from "../tasks/context-key";
+
+const TEST_DB_PATH = "./test-context-key-db.sqlite";
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(() => {
+  closeDb();
+  try {
+    unlinkSync(TEST_DB_PATH);
+    unlinkSync(`${TEST_DB_PATH}-wal`);
+    unlinkSync(`${TEST_DB_PATH}-shm`);
+  } catch {
+    // ignore
+  }
+});
+
+describe("contextKey persistence + lookup", () => {
+  test("createTaskExtended persists contextKey and getInProgressTasksByContextKey returns it", () => {
+    const agent = createAgent({
+      name: "ctx-key-agent-1",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    const key = slackContextKey({ channelId: "C_TEST_1", threadTs: "1700000000.000001" });
+    const task = createTaskExtended("Hello", { agentId: agent.id, contextKey: key });
+
+    expect(task.contextKey).toBe(key);
+
+    const siblings = getInProgressTasksByContextKey(key);
+    expect(siblings.map((t) => t.id)).toContain(task.id);
+  });
+
+  test("getInProgressTasksByContextKey excludes terminal tasks", () => {
+    const agent = createAgent({
+      name: "ctx-key-agent-2",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    const key = slackContextKey({ channelId: "C_TEST_2", threadTs: "1700000000.000002" });
+    const done = createTaskExtended("Done task", { agentId: agent.id, contextKey: key });
+    const pending = createTaskExtended("Pending task", { agentId: agent.id, contextKey: key });
+
+    completeTask(done.id, "ok");
+
+    const siblings = getInProgressTasksByContextKey(key);
+    const ids = siblings.map((t) => t.id);
+    expect(ids).toContain(pending.id);
+    expect(ids).not.toContain(done.id);
+  });
+
+  test("getInProgressTasksByContextKey returns empty for unknown key", () => {
+    const results = getInProgressTasksByContextKey("task:slack:C_NONE:0");
+    expect(results).toEqual([]);
+  });
+
+  test("child task inherits contextKey from parent", () => {
+    const agent = createAgent({
+      name: "ctx-key-agent-3",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    const key = slackContextKey({ channelId: "C_TEST_3", threadTs: "1700000000.000003" });
+    const parent = createTaskExtended("Parent", { agentId: agent.id, contextKey: key });
+    const child = createTaskExtended("Child", { agentId: agent.id, parentTaskId: parent.id });
+
+    expect(child.contextKey).toBe(key);
+  });
+});