@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/src/tests/workflow-run-finished-event.test.ts

@@ -0,0 +1,263 @@
+/**
+ * `workflow.run.finished`: every run, top-level or child, emits it once after
+ * commit when it turns terminal, so an event-mode `wait` can resume when any
+ * run ends.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { recordWorkflowPreflightFailure } from "../be/automation-preflight";
+import * as db from "../be/db";
+import {
+  closeDb,
+  createWorkflow,
+  createWorkflowRun,
+  getDbClient,
+  getWaitStateByStepId,
+  getWorkflowRun,
+  getWorkflowRunStepsByRunId,
+  initDb,
+  updateWorkflowRun,
+} from "../be/db";
+import { cancelLiveWorkflowTreeRuns } from "../be/db/workflow-runs";
+import type { Workflow, WorkflowDefinition } from "../types";
+import { startWorkflowExecution } from "../workflows/engine";
+import { workflowEventBus } from "../workflows/event-bus";
+import type { ExecutorDependencies } from "../workflows/executors/base";
+import { createExecutorRegistry } from "../workflows/executors/registry";
+import { _resetWaitBusSubscriptionsForTests, initWaitBusSubscriptions } from "../workflows/resume";
+
+const TEST_DB_PATH = "./test-workflow-run-finished-event.sqlite";
+const EVENT = "workflow.run.finished";
+
+const deps: ExecutorDependencies = {
+  db: db as typeof import("../be/db"),
+  eventBus: workflowEventBus,
+  interpolate: (t: string) => t,
+};
+
+type FinishedPayload = { runId: string; workflowId: string; status: string };
+
+const received: FinishedPayload[] = [];
+const onFinished = (data: unknown) => received.push(data as FinishedPayload);
+
+beforeAll(async () => {
+  await unlink(TEST_DB_PATH).catch(() => {});
+  initDb(TEST_DB_PATH);
+  workflowEventBus.on(EVENT, onFinished);
+});
+
+afterAll(async () => {
+  workflowEventBus.off(EVENT, onFinished);
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+});
+
+afterEach(() => {
+  _resetWaitBusSubscriptionsForTests();
+});
+
+async function makeWorkflow(name: string, def?: WorkflowDefinition): Promise<Workflow> {
+  return createWorkflow({
+    name: `${name}-${crypto.randomUUID()}`,
+    definition: def ?? {
+      nodes: [{ id: "n", type: "notify", config: { channel: "swarm", template: "x" } }],
+    },
+  });
+}
+
+async function newRun(workflowId: string): Promise<string> {
+  const id = crypto.randomUUID();
+  await createWorkflowRun({ id, workflowId });
+  return id;
+}
+
+const eventsFor = (runId: string) => received.filter((event) => event.runId === runId);
+
+// The emit goes through afterCommit and a dynamic import, so let it settle.
+const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+
+async function waitFor(predicate: () => boolean | Promise<boolean>, timeoutMs = 2000) {
+  const t0 = Date.now();
+  while (!(await predicate())) {
+    if (Date.now() - t0 > timeoutMs) throw new Error("waitFor: timeout");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+describe("workflow.run.finished", () => {
+  test("fires once per terminal transition, with the run id as runId", async () => {
+    const wf = await makeWorkflow("run-finished-once");
+    const runId = await newRun(wf.id);
+
+    await updateWorkflowRun(runId, { status: "waiting" });
+    await settle();
+    expect(eventsFor(runId)).toEqual([]);
+
+    await updateWorkflowRun(runId, { status: "failed", error: "boom" });
+    await waitFor(() => eventsFor(runId).length === 1);
+    expect(eventsFor(runId)[0]).toEqual({ runId, workflowId: wf.id, status: "failed" });
+    expect(eventsFor(runId)[0]).not.toHaveProperty("workflowRunId");
+    expect(eventsFor(runId)[0]).not.toHaveProperty("_runId");
+
+    // Later writes to the terminal run, with or without the same status, stay silent.
+    await updateWorkflowRun(runId, { context: { late: true } });
+    await updateWorkflowRun(runId, { status: "failed", error: "boom again" });
+    await settle();
+    expect(eventsFor(runId)).toHaveLength(1);
+
+    // A retry reopens the run; its next end is a new transition.
+    await updateWorkflowRun(runId, { status: "running" });
+    await updateWorkflowRun(runId, { status: "completed" });
+    await waitFor(() => eventsFor(runId).length === 2);
+    expect(eventsFor(runId)[1]?.status).toBe("completed");
+
+    // A terminal run moved to another terminal status, with no reopen, stays silent.
+    const relabelled = await newRun(wf.id);
+    await updateWorkflowRun(relabelled, { status: "completed" });
+    await waitFor(() => eventsFor(relabelled).length === 1);
+    await updateWorkflowRun(relabelled, { status: "failed", error: "late failure" });
+    await settle();
+    expect(eventsFor(relabelled)).toEqual([
+      { runId: relabelled, workflowId: wf.id, status: "completed" },
+    ]);
+  });
+
+  test("fires only after commit, and never for a rolled-back end", async () => {
+    const wf = await makeWorkflow("run-finished-commit");
+    const committed = await newRun(wf.id);
+    const rolledBack = await newRun(wf.id);
+
+    await getDbClient().transaction(async () => {
+      await updateWorkflowRun(committed, { status: "completed" });
+      await settle();
+      expect(eventsFor(committed)).toEqual([]);
+    });
+    await waitFor(() => eventsFor(committed).length === 1);
+
+    await expect(
+      getDbClient().transaction(async () => {
+        await updateWorkflowRun(rolledBack, { status: "skipped" });
+        throw new Error("roll back");
+      }),
+    ).rejects.toThrow("roll back");
+    await settle();
+    expect(eventsFor(rolledBack)).toEqual([]);
+    expect((await getWorkflowRun(rolledBack))?.status).toBe("running");
+  });
+
+  test("cancelLiveWorkflowTreeRuns fires for each run it cancels, not for terminal runs", async () => {
+    const wf = await makeWorkflow("run-finished-tree-cancel");
+    const live = await newRun(wf.id);
+    const waiting = await newRun(wf.id);
+    const done = await newRun(wf.id);
+    await updateWorkflowRun(waiting, { status: "waiting" });
+    await updateWorkflowRun(done, { status: "completed" });
+    await waitFor(() => eventsFor(done).length === 1);
+
+    const now = new Date().toISOString();
+    await getDbClient().transaction(() =>
+      cancelLiveWorkflowTreeRuns([live, waiting, done], "tree cancelled", now),
+    );
+
+    await waitFor(() => eventsFor(live).length === 1 && eventsFor(waiting).length === 1);
+    expect(eventsFor(live)[0]).toEqual({ runId: live, workflowId: wf.id, status: "cancelled" });
+    expect(eventsFor(waiting)[0]?.status).toBe("cancelled");
+    await settle();
+    expect(eventsFor(done)).toHaveLength(1);
+  });
+
+  test("a preflight failure run fires once, a deduplicated repeat does not", async () => {
+    const wf = await makeWorkflow("run-finished-preflight");
+    const input = {
+      workflowId: wf.id,
+      triggerType: "manual" as const,
+      triggerData: {},
+      failureReason: "needs_setup: slack",
+    };
+    const first = await recordWorkflowPreflightFailure(input);
+    await waitFor(() => eventsFor(first.runId).length === 1);
+    expect(eventsFor(first.runId)[0]?.status).toBe("failed");
+
+    const repeat = await recordWorkflowPreflightFailure(input);
+    expect(repeat.runId).toBe(first.runId);
+    await settle();
+    expect(eventsFor(first.runId)).toHaveLength(1);
+  });
+
+  test("a global wait filtered on a detached run's id resumes when that run ends", async () => {
+    const registry = createExecutorRegistry(deps);
+
+    // The detached run parks on a signal, so it stays live until the test ends it.
+    const target = await makeWorkflow("run-finished-target", {
+      nodes: [
+        {
+          id: "hold",
+          type: "wait",
+          config: { mode: "event", eventName: "test.release-target", scope: "global" },
+          next: { event: "end" },
+        },
+        { id: "end", type: "notify", config: { channel: "swarm", template: "released" } },
+      ],
+    });
+    const targetRunId = await startWorkflowExecution(target, {}, registry);
+    expect((await getWorkflowRun(targetRunId))?.status).toBe("waiting");
+
+    const waiter = await makeWorkflow("run-finished-waiter", {
+      nodes: [
+        {
+          id: "watch",
+          type: "wait",
+          config: {
+            mode: "event",
+            eventName: EVENT,
+            scope: "global",
+            filter: { runId: targetRunId },
+          },
+          next: { event: "after" },
+        },
+        { id: "after", type: "notify", config: { channel: "swarm", template: "target ended" } },
+      ],
+    });
+    const waiterRunId = await startWorkflowExecution(waiter, {}, registry);
+    // Control: a run-scoped wait on the same event must never match another run's end.
+    const scoped = await makeWorkflow("run-finished-run-scope", {
+      nodes: [
+        {
+          id: "watch",
+          type: "wait",
+          config: { mode: "event", eventName: EVENT, scope: "run" },
+        },
+      ],
+    });
+    const scopedRunId = await startWorkflowExecution(scoped, {}, registry);
+    await initWaitBusSubscriptions(registry);
+
+    const watchStep = async (runId: string) =>
+      (await getWorkflowRunStepsByRunId(runId)).find((step) => step.nodeId === "watch");
+    const watch = await watchStep(waiterRunId);
+    const scopedWatch = await watchStep(scopedRunId);
+    expect((await getWaitStateByStepId(watch!.id))?.status).toBe("pending");
+
+    // Another run ending does not match the filter.
+    const other = await newRun(target.id);
+    await updateWorkflowRun(other, { status: "completed" });
+    await waitFor(() => eventsFor(other).length === 1);
+    await settle();
+    expect((await getWaitStateByStepId(watch!.id))?.status).toBe("pending");
+
+    workflowEventBus.emit("test.release-target", {});
+    await waitFor(async () => (await getWorkflowRun(targetRunId))?.status === "completed");
+    await waitFor(async () => (await getWaitStateByStepId(watch!.id))?.status === "fired");
+
+    const fired = await getWaitStateByStepId(watch!.id);
+    expect(fired?.firedPayload).toEqual({
+      runId: targetRunId,
+      workflowId: target.id,
+      status: "completed",
+    });
+    await waitFor(async () => (await getWorkflowRun(waiterRunId))?.status === "completed");
+    expect((await getWaitStateByStepId(scopedWatch!.id))?.status).toBe("pending");
+  });
+});

package/src/tests/workflow-swarm-script.test.ts

@@ -760,6 +760,40 @@ describe("SwarmScriptExecutor", () => {
     expect(result.output?.exitCode).not.toBe(0);
   });
 
+  skip(
+    "meta.signal abort kills the script before its side effect",
+    async () => {
+      const marker = `/tmp/swarm-script-abort-${crypto.randomUUID()}`;
+      await saveScript(
+        "one-shot",
+        `export default async () => { await new Promise(r => setTimeout(r, 1500)); await Bun.write(${JSON.stringify(marker)}, "ran"); return { done: true }; };`,
+      );
+      const executor = new SwarmScriptExecutor(deps);
+      const wf = await makeWorkflow({ nodes: [] });
+      const controller = new AbortController();
+      setTimeout(() => controller.abort(new Error("Step timed out")), 300);
+      const result = await executor.run({
+        config: { scriptName: "one-shot", timeoutMs: 30_000 },
+        context: {},
+        meta: {
+          runId: crypto.randomUUID(),
+          stepId: crypto.randomUUID(),
+          nodeId: "script",
+          workflowId: wf.id,
+          dryRun: false,
+          signal: controller.signal,
+        },
+      });
+
+      expect(result.status).toBe("failed");
+      expect(result.error).toContain("killed");
+      // Past the point where the script would have written the marker.
+      await Bun.sleep(1_800);
+      expect(await Bun.file(marker).exists()).toBe(false);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
   skip("Failure in the script surfaces as a workflow-node failure", async () => {
     await saveScript("throws", `export default async () => { throw new Error("boom"); };`);
     const executor = new SwarmScriptExecutor(deps);

package/src/tools/inject-learning.ts

@@ -73,7 +73,7 @@ export const registerInjectLearningTool = (server: McpServer) => {
       // Generate and store embedding (async, best-effort)
       try {
         const provider = getEmbeddingProvider();
-        const embedding = await provider.embed(memory.content);
+        const embedding = await provider.embed(memory.content, { kind: "document" });
         if (embedding) {
           await store.updateEmbedding(memory.id, embedding, provider.name);
         }

package/src/tools/memory-edit.ts

@@ -183,7 +183,7 @@ export const registerMemoryEditTool = (server: McpServer) => {
           content !== undefined || oldString !== undefined || newString !== undefined;
         if (result.changed && (newKey === undefined || contentEdited)) {
           const provider = getEmbeddingProvider();
-          const embedding = await provider.embed(result.memory.content);
+          const embedding = await provider.embed(result.memory.content, { kind: "document" });
           if (embedding) await store.updateEmbedding(result.memory.id, embedding, provider.name);
           try {
             // Edit path: prune links derived from removed content (sequel links survive).

package/src/tools/memory-search.ts

@@ -120,7 +120,7 @@ export const registerMemorySearchTool = (server: McpServer) => {
       // Try vector search first
       const provider = getEmbeddingProvider();
       const store = getMemoryStore();
-      const queryEmbedding = await provider.embed(query);
+      const queryEmbedding = await provider.embed(query, { kind: "query" });
 
       const candidateLimit = limit * CANDIDATE_SET_MULTIPLIER;
       const candidates = await searchMemoryCandidates(

package/src/tools/script-common.ts

@@ -16,6 +16,7 @@ export const SCRIPT_TRANSPORT_ERROR =
 export const scriptNameSchema = z.string().min(1).max(200);
 export const scriptScopeSchema = z.enum(["agent", "global"]);
 export const scriptFsModeSchema = z.enum(["none", "workspace-rw"]);
+export const scriptExecutorSchema = z.enum(["native", "quickjs"]);
 
 export const scriptToolOutputSchema = swarmToolOutputSchema({
   status: z.number().optional(),

package/src/tools/script-run.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { createToolRegistrar } from "@/tools/utils";
 import {
   proxyScriptsApi,
+  scriptExecutorSchema,
   scriptFsModeSchema,
   scriptNameSchema,
   scriptScopeSchema,
@@ -66,6 +67,12 @@ export const registerScriptRunTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        executor: scriptExecutorSchema
+          .nullable()
+          .optional()
+          .describe(
+            'Optional executor override ("native" or "quickjs"). When omitted, named scripts use their saved executor or SCRIPT_EXECUTOR.',
+          ),
         idempotencyKey: z
           .string()
           .max(200)

package/src/tools/script-upsert.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { createToolRegistrar } from "@/tools/utils";
 import {
   proxyScriptsApi,
+  scriptExecutorSchema,
   scriptFsModeSchema,
   scriptNameSchema,
   scriptScopeSchema,
@@ -33,6 +34,12 @@ export const registerScriptUpsertTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        executor: scriptExecutorSchema
+          .nullable()
+          .optional()
+          .describe(
+            'Optional per-script executor override ("native" or "quickjs"). Null or omitted inherits SCRIPT_EXECUTOR.',
+          ),
       }),
       outputSchema: scriptToolOutputSchema,
     },

package/src/tools/store-progress.ts

@@ -13,6 +13,11 @@ import {
   updateAgentStatusFromCapacity,
   updateTaskProgress,
 } from "@/be/db";
+import {
+  LEARNING_MAX_TAGS,
+  storeTaskLearning,
+  type TaskLearningResult,
+} from "@/be/memory/task-learning";
 import {
   CitationInputSchema,
   getTaskCitations,
@@ -114,8 +119,30 @@ export const storeProgressOutputSchema = swarmToolOutputSchema({
     .describe(
       "Present only when this progress text reads as blocked-waiting: milliseconds since the task's prior update. Drives the store-progress nudge toward defer-task.",
     ),
+  learning: z
+    .looseObject({
+      status: z.string().optional(),
+      key: z.string().optional(),
+      memoryId: z.string().optional(),
+      workstream: z.string().optional(),
+      similarity: z.number().optional(),
+      error: z.string().optional(),
+    })
+    .optional()
+    .describe(
+      "Present when the call carried a learning: stored, replayed (same text already stored for this task), duplicate (an existing swarm memory at key/memoryId says the same; similarity is the raw cosine), or failed with error.",
+    ),
 });
 
+function learningSentence(result: TaskLearningResult): string {
+  if (result.status === "stored") return `Learning stored at ${result.key}.`;
+  if (result.status === "replayed") return `Learning already stored at ${result.key}; skipped.`;
+  if (result.status === "duplicate") {
+    return `Learning not stored: it matches ${result.key} (similarity ${result.similarity}).`;
+  }
+  return `Learning not stored: ${result.error}.`;
+}
+
 export const registerStoreProgressTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "store-progress",
@@ -165,6 +192,19 @@ export const registerStoreProgressTool = (server: McpServer) => {
           .describe(
             'Claim sources, upserted by index across calls. Use only for factual claims the reader cannot already see in the thread or task tree, 1-2 sources; none on delegation, routing, acks, or status replies. Reference each one in output with [citation:N], or set general: true for a source that backs the whole answer (it renders under "General sources"). ref per kind: task = task UUID; memory = memory UUID (optional quote must appear verbatim in it); github = owner/repo#N, owner/repo@<sha>, or a github.com pull, issues, or commit URL; slack = permalink or channel/ts; agent-fs = file path; page = page id; script-run = script run id; url = http(s) URL. The first completing call is refused, and the task stays in progress, if a marker has no entry, a citation fails validation, or a non-general citation is unreferenced; the response lists each problem. After one refusal, completion proceeds and those markers and sources are dropped from rendered output. At most 50 citations per call/task, refs up to 2048 characters, labels up to 200. Invalid or oversized batches are ignored; existing indices can still be updated at capacity.',
           ),
+        learning: z
+          .union([
+            z.string(),
+            z.object({
+              text: z.string(),
+              workstream: z.string().optional(),
+              tags: z.array(z.string()).optional(),
+            }),
+          ])
+          .optional()
+          .describe(
+            `A lesson to keep. Add one only when it would change how the next agent works: a gotcha, a dead end, a pattern that worked. Not a progress line. Stored as a swarm memory at /learnings/<workstream>/<slug>, tagged "learning" and tied to this task. The first line of text is the title. At most ~500 tokens and ${LEARNING_MAX_TAGS} kebab tags. workstream defaults to the task's repo name, else "general". Send it on or before the completing call: a call on a finished task stores nothing. A failed learning write is reported in the result and never blocks the progress update.`,
+          ),
         persistMemory: z
           .boolean()
           .optional()
@@ -193,6 +233,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         failureReason,
         attachments,
         citations,
+        learning,
         persistMemory,
         force,
       },
@@ -332,6 +373,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         }
       }
 
+      let learningWrite: Promise<TaskLearningResult> | undefined;
       const result = await getDbClient().transaction(async () => {
         const agent = await getAgentById(requestInfo.agentId ?? "");
 
@@ -435,6 +477,29 @@ export const registerStoreProgressTool = (server: McpServer) => {
           await upsertTaskCitations(taskId, citations);
         }
 
+        // A finished task takes no new writes, learnings included.
+        if (learning && isTerminal) {
+          learningWrite = Promise.resolve({
+            status: "failed",
+            error: "the task is already finished; use memory-store",
+          });
+        } else if (learning) {
+          // Post-commit, so a rolled-back progress write never leaves a learning
+          // behind, and a failed learning write never rolls back the progress.
+          learningWrite = new Promise((resolve) => {
+            getDbClient().afterCommit(() =>
+              storeTaskLearning({
+                agentId: agent.id,
+                isLead: agent.isLead === true,
+                task: existingTask,
+                learning,
+              }).then(resolve, (err) =>
+                resolve({ status: "failed", error: scrubSecrets(String(err)) }),
+              ),
+            );
+          });
+        }
+
         // Idempotency guard: short-circuit terminal-status writes (completed/failed)
         // BEFORE any side-effects fire (event emission, memory write, follow-up task,
         // business-use ensure). Without this, a multi-session race causes duplicate
@@ -627,7 +692,11 @@ export const registerStoreProgressTool = (server: McpServer) => {
         });
       }
 
-      const { success, message } = result;
+      const learningResult = await learningWrite;
+      const { success } = result;
+      const message = learningResult
+        ? `${result.message} ${learningSentence(learningResult)}`
+        : result.message;
       const task = result.task
         ? {
             id: result.task.id,
@@ -646,6 +715,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         typeof result.blockedWaitingElapsedMs === "number"
           ? { blockedWaitingElapsedMs: result.blockedWaitingElapsedMs }
           : {}),
+        ...(learningResult ? { learning: learningResult } : {}),
       };
       const warnings =
         success && status === "completed"

package/src/tools/utils.ts

@@ -297,6 +297,17 @@ const storeProgressBlockedWaitingNudge = (r: SwarmToolResult): string | undefine
   return `That reads as blocked-waiting, ${formatIdleDuration(ms)} since your last update — keep working if you can, and if the wait is genuinely long, defer-task is one way to resume later instead of polling.`;
 };
 
+const storeProgressNudge = (r: SwarmToolResult): string | undefined => {
+  const learning = (r.data as { learning?: { status?: unknown; memoryId?: unknown } } | undefined)
+    ?.learning;
+  // nudgeMiddleware permits exactly one steer: the duplicate-learning steer
+  // names a concrete next call, so it wins over the blocked-waiting reminder.
+  if (r.ok && learning?.status === "duplicate" && typeof learning.memoryId === "string") {
+    return `That learning repeats memory ${learning.memoryId}; if your text adds something, memory-edit that memory instead of storing a new one.`;
+  }
+  return storeProgressBlockedWaitingNudge(r);
+};
+
 const workflowLongScriptTimeoutNudge = (r: SwarmToolResult): string | undefined => {
   if (!r.ok) return undefined;
   const hint = (r.data as { longScriptTimeoutHint?: unknown } | undefined)?.longScriptTimeoutHint;
@@ -311,7 +322,7 @@ const workflowLongScriptTimeoutNudge = (r: SwarmToolResult): string | undefined
 export const NUDGES: Record<string, (result: SwarmToolResult) => string | undefined> = {
   "defer-task": (r) =>
     r.ok ? "Stop working on this task now; the wake-up task will carry your note." : undefined,
-  "store-progress": storeProgressBlockedWaitingNudge,
+  "store-progress": storeProgressNudge,
   "script-run": scriptRunNudge,
   "script-upsert": scriptAuthoringNudge,
   "launch-script-run": scriptAuthoringNudge,