@desplega.ai/agent-swarm 1.147.0 → 1.149.0

package/src/tests/store-progress-blocked-waiting-gate.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Regression coverage for the `store-progress` blocked-waiting nudge gate
+ * (src/tools/store-progress.ts). Two swarm-review findings on PR #1472:
+ *
+ * 1. The terminal gate only checked `existingTask.status` (the state BEFORE
+ *    this call), never the incoming `status` argument. A completing call
+ *    (`status: "completed"`) whose progress text happened to match the
+ *    blocked-waiting pattern (e.g. "awaiting review") still set
+ *    `blockedWaitingElapsedMs`, nudging the agent to `defer-task` on the very
+ *    turn it finished.
+ * 2. `blockedWaitingElapsedMs` had no floor, so two check-ins seconds apart
+ *    could fire "under a minute since your last update — call defer-task",
+ *    which buys nothing over just checking in again shortly.
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, createAgent, createTaskExtended, getDbClient, initDb, startTask } from "../be/db";
+import { registerStoreProgressTool } from "../tools/store-progress";
+
+const TEST_DB_PATH = "./test-store-progress-blocked-waiting-gate.sqlite";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<unknown>;
+};
+
+type StoreProgressResult = {
+  structuredContent: {
+    success: boolean;
+    blockedWaitingElapsedMs?: number;
+  };
+};
+
+function buildServer() {
+  const server = new McpServer({
+    name: "store-progress-blocked-waiting-gate-test",
+    version: "1.0.0",
+  });
+  registerStoreProgressTool(server);
+  const registered = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+  const tool = registered["store-progress"];
+  if (!tool) throw new Error("store-progress tool not registered");
+  return tool;
+}
+
+describe("store-progress handler — blocked-waiting nudge gate", () => {
+  let agentId: string;
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    const agent = await createAgent({
+      name: "Blocked Waiting Gate Worker",
+      description: "Agent for blocked-waiting gate regression tests",
+      role: "worker",
+      isLead: false,
+      status: "busy",
+      maxTasks: 1,
+      capabilities: [],
+    });
+    agentId = agent.id;
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+  });
+
+  function buildMeta() {
+    return { requestInfo: { headers: { "x-agent-id": agentId } } };
+  }
+
+  async function ageLastUpdate(taskId: string, msAgo: number) {
+    await getDbClient().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+      new Date(Date.now() - msAgo).toISOString(),
+      taskId,
+    ]);
+  }
+
+  test("a completing call with blocked-waiting-shaped text does not nudge", async () => {
+    const task = await createTaskExtended("completing call with awaiting text", {
+      agentId,
+      source: "mcp",
+      priority: 50,
+    });
+    await startTask(task.id);
+    // Old enough that, absent the fix, this would clear the elapsed-time floor.
+    await ageLastUpdate(task.id, 10 * 60_000);
+
+    const tool = buildServer();
+    const result = (await tool.handler(
+      {
+        taskId: task.id,
+        status: "completed",
+        output: "done",
+        progress: "awaiting review",
+      },
+      buildMeta(),
+    )) as StoreProgressResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.blockedWaitingElapsedMs).toBeUndefined();
+  });
+
+  test("elapsed time below the 3-minute floor does not nudge", async () => {
+    const task = await createTaskExtended("progress call under the floor", {
+      agentId,
+      source: "mcp",
+      priority: 50,
+    });
+    await startTask(task.id);
+    await ageLastUpdate(task.id, 30_000);
+
+    const tool = buildServer();
+    const result = (await tool.handler(
+      { taskId: task.id, progress: "still waiting on the API team" },
+      buildMeta(),
+    )) as StoreProgressResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.blockedWaitingElapsedMs).toBeUndefined();
+  });
+
+  test("a non-terminal call past the floor with matching text still nudges (baseline)", async () => {
+    const task = await createTaskExtended("progress call past the floor", {
+      agentId,
+      source: "mcp",
+      priority: 50,
+    });
+    await startTask(task.id);
+    await ageLastUpdate(task.id, 5 * 60_000);
+
+    const tool = buildServer();
+    const result = (await tool.handler(
+      { taskId: task.id, progress: "still waiting on the API team" },
+      buildMeta(),
+    )) as StoreProgressResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.blockedWaitingElapsedMs).toBeGreaterThanOrEqual(3 * 60_000);
+  });
+});

package/src/tests/swarm-tool-result-gate.test.ts

@@ -317,6 +317,30 @@ describe("finalizeSwarmToolResult", () => {
     expect((withoutHint.structuredContent as { nudge?: string }).nudge).toBeUndefined();
   });
 
+  test("NUDGES map: store-progress steers to defer-task only when blocked-waiting was detected", async () => {
+    const blocked = await finalizeSwarmToolResult("store-progress", {
+      ok: true,
+      message: 'Progress stored for task "t-1".',
+      data: { task: { id: "t-1", status: "in_progress" }, blockedWaitingElapsedMs: 5 * 60_000 },
+    });
+    const nudge = (blocked.structuredContent as { nudge?: string }).nudge;
+    expect(nudge).toContain("defer-task");
+    expect(nudge).toContain("5m");
+
+    const ordinary = await finalizeSwarmToolResult("store-progress", {
+      ok: true,
+      message: 'Progress stored for task "t-1".',
+      data: { task: { id: "t-1", status: "in_progress" } },
+    });
+    expect((ordinary.structuredContent as { nudge?: string }).nudge).toBeUndefined();
+
+    const failed = await finalizeSwarmToolResult("store-progress", {
+      ok: false,
+      message: "Task not found.",
+    });
+    expect((failed.structuredContent as { nudge?: string }).nudge).toBeUndefined();
+  });
+
   test("data with no details auto-renders into the text channel (completeness guarantee)", async () => {
     const result = await finalizeSwarmToolResult("some-tool", {
       ok: true,

package/src/tests/task-tool-manifest.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { validateConfigValue } from "../be/swarm-config-guard";
+import { parseTaskToolManifest, selectTaskTools } from "../utils/task-tool-manifest";
+
+const scheduleId = "12345678-1234-4234-8234-123456789abc";
+
+describe("task tool manifests", () => {
+  test("matches exact keys and lets an empty schedule opt out of its type", () => {
+    const manifest = parseTaskToolManifest(
+      JSON.stringify({
+        taskTypes: { review: ["script-run", "script-run", "get-tasks"] },
+        schedules: { [scheduleId]: [] },
+      }),
+    );
+    expect(selectTaskTools(manifest, { taskType: "review" })).toEqual(["script-run", "get-tasks"]);
+    expect(selectTaskTools(manifest, { taskType: "review", scheduleId })).toEqual([]);
+    expect(selectTaskTools(manifest, { taskType: "review-follow-up" })).toEqual([]);
+    expect(selectTaskTools(manifest, { taskType: "toString" })).toEqual([]);
+  });
+
+  test("Slack tools only preload for a task carrying Slack context", () => {
+    const manifest = parseTaskToolManifest('{"taskTypes":{"review":["slack-read","script-run"]}}');
+    expect(selectTaskTools(manifest, { taskType: "review" })).toEqual(["script-run"]);
+    expect(selectTaskTools(manifest, { taskType: "review", slackChannelId: "C123" })).toEqual([
+      "slack-read",
+      "script-run",
+    ]);
+  });
+
+  test("config writes reject unknown tools, invalid shapes, and oversized selections", () => {
+    for (const value of [
+      "not json",
+      "null",
+      "[]",
+      '{"taskTypes":{"review":["not-a-tool"]}}',
+      '{"taskTypes":{"review":"script-run"}}',
+      '{"schedules":{"not-a-uuid":["script-run"]}}',
+      '{"taskType":{"review":["script-run"]}}',
+      JSON.stringify({ taskTypes: { review: Array(17).fill("script-run") } }),
+    ]) {
+      expect(validateConfigValue("TASK_TOOL_MANIFESTS", value)).toContain("Invalid");
+    }
+    expect(validateConfigValue("TASK_TOOL_MANIFESTS", "{}")).toBeNull();
+    expect(validateConfigValue("TASK_TOOL_PRELOAD_ENABLED", "false")).toBeNull();
+    expect(validateConfigValue("TASK_TOOL_PRELOAD_ENABLED", "treu")).toContain("Invalid");
+  });
+});

package/src/tests/task-tool-preload-mcp.test.ts

@@ -0,0 +1,125 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import { createServer as createHttpServer } from "node:http";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { closeDb, createAgent, createTaskExtended, initDb, upsertSwarmConfig } from "../be/db";
+import { handleMcp } from "../http/mcp";
+import { listenOnFreePort } from "./test-net";
+
+const dbPath = "./test-task-tool-preload.sqlite";
+const transports: Record<string, StreamableHTTPServerTransport> = {};
+const agents: Record<string, string> = {};
+const activity: Record<string, number> = {};
+const clients: Client[] = [];
+const server = createHttpServer(async (req, res) => {
+  if (await handleMcp(req, res, transports, activity, agents)) return;
+  res.writeHead(404).end();
+});
+let url: URL;
+let agentId: string;
+const savedEnv = {
+  TASK_TOOL_PRELOAD_ENABLED: process.env.TASK_TOOL_PRELOAD_ENABLED,
+  TASK_TOOL_MANIFESTS: process.env.TASK_TOOL_MANIFESTS,
+  SCRIPTS_ONLY_MCP: process.env.SCRIPTS_ONLY_MCP,
+};
+
+beforeAll(async () => {
+  delete process.env.TASK_TOOL_PRELOAD_ENABLED;
+  delete process.env.TASK_TOOL_MANIFESTS;
+  delete process.env.SCRIPTS_ONLY_MCP;
+  initDb(dbPath);
+  agentId = (await createAgent({ name: "manifest-worker", isLead: false, status: "idle" })).id;
+  url = new URL(`http://127.0.0.1:${await listenOnFreePort(server, "127.0.0.1")}/mcp`);
+});
+
+afterAll(async () => {
+  await Promise.all(clients.map((client) => client.close()));
+  await Promise.all(Object.values(transports).map((transport) => transport.close()));
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) await rm(dbPath + suffix, { force: true });
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+async function connect(taskId?: string): Promise<Client> {
+  const client = new Client({ name: "manifest-test", version: "1" });
+  clients.push(client);
+  await client.connect(
+    new StreamableHTTPClientTransport(url, {
+      requestInit: {
+        headers: {
+          "X-Agent-ID": agentId,
+          ...(taskId ? { "X-Source-Task-Id": taskId } : {}),
+        },
+      },
+    }),
+  );
+  return client;
+}
+
+async function configure(key: string, value: string) {
+  await upsertSwarmConfig({ scope: "agent", scopeId: agentId, key, value });
+}
+
+async function pins(client: Client): Promise<string[]> {
+  return (await client.listTools()).tools
+    .filter((tool) => tool._meta?.["anthropic/alwaysLoad"] === true)
+    .map((tool) => tool.name)
+    .sort();
+}
+
+test("wire response is default-off, per-task, additive, and fixed for one MCP session", async () => {
+  const task = await createTaskExtended("review fixture", { agentId, taskType: "review" });
+  const other = await createTaskExtended("other fixture", { agentId, taskType: "other" });
+  const foreign = await createTaskExtended("unowned", { taskType: "review" });
+  await configure("TASK_TOOL_MANIFESTS", '{"taskTypes":{"review":["script-run","get-tasks"]}}');
+  const off = await connect(task.id);
+  const baseline = (await off.listTools()).tools;
+  expect(baseline.some((tool) => tool.name === "script-run")).toBe(true);
+  expect(await pins(off)).toEqual([]);
+  expect(off.getInstructions()).toBeUndefined();
+
+  await configure("TASK_TOOL_PRELOAD_ENABLED", "true");
+  const [on, unmatched, unowned, missing] = await Promise.all([
+    connect(task.id),
+    connect(other.id),
+    connect(foreign.id),
+    connect(),
+  ]);
+  expect(await pins(on)).toEqual(["get-tasks", "script-run"]);
+  expect(on.getInstructions()).toContain("call it directly");
+  expect(await pins(unmatched)).toEqual([]);
+  expect(await pins(unowned)).toEqual([]);
+  expect(await pins(missing)).toEqual([]);
+  expect(await pins(off)).toEqual([]);
+  expect((await on.listTools()).tools.map((tool) => tool.name)).toEqual(
+    baseline.map((tool) => tool.name),
+  );
+  const result = await on.callTool({ name: "get-tasks", arguments: { mineOnly: true } });
+  expect(result.isError).toBe(false);
+
+  // Explicit per-agent off wins even when the deployment default is on.
+  process.env.TASK_TOOL_PRELOAD_ENABLED = "true";
+  await configure("TASK_TOOL_PRELOAD_ENABLED", "false");
+  expect(await pins(await connect(task.id))).toEqual([]);
+  expect(await pins(on)).toEqual(["get-tasks", "script-run"]);
+
+  await configure("TASK_TOOL_PRELOAD_ENABLED", "true");
+  await configure("TASK_TOOL_MANIFESTS", "invalid deployment JSON");
+  expect(await pins(await connect(task.id))).toEqual([]);
+});
+
+test("a manifest cannot expand the scripts-only capability surface", async () => {
+  const task = await createTaskExtended("script fixture", { agentId, taskType: "script" });
+  await configure("TASK_TOOL_PRELOAD_ENABLED", "true");
+  await configure("TASK_TOOL_MANIFESTS", '{"taskTypes":{"script":["script-run","get-tasks"]}}');
+  await configure("SCRIPTS_ONLY_MCP", "true");
+  const client = await connect(task.id);
+  expect(await pins(client)).toEqual(["script-run"]);
+  expect((await client.listTools()).tools.some((tool) => tool.name === "get-tasks")).toBe(false);
+});

package/src/tests/task-tools-ctx.test.ts

@@ -85,6 +85,7 @@ describe("task tool ctx", () => {
     const result = await sendTaskHandler(ownerCtx({ agentId: sender.id }), {
       task: "ordinary direct assignment",
       agentId: lead.id,
+      routingReason: "skill",
       offerMode: false,
       allowDuplicate: false,
     });
@@ -106,6 +107,7 @@ describe("task tool ctx", () => {
     const result = await sendTaskHandler(ownerCtx({ agentId: sender.id }), {
       task: "ordinary offer",
       agentId: lead.id,
+      routingReason: "skill",
       offerMode: true,
       allowDuplicate: false,
     });

package/src/tests/tool-output-agent-id.test.ts

@@ -164,6 +164,7 @@ describe("agent-id fields accept non-UUID agent ids", () => {
   test("send-task input accepts a slug agentId target", () => {
     const parsed = sendTaskInputSchema.parse({
       agentId: SLUG_WORKER_ID,
+      routingReason: "skill",
       task: "do the thing",
     });
     expect(parsed.agentId).toBe(SLUG_WORKER_ID);

package/src/tests/ui-followup-lead-delegation.test.ts

@@ -165,7 +165,12 @@ describe("session-UI follow-up → Lead → onward delegation", () => {
     // provenance, not a requirement.
     const delegated = await callSendTask(
       mcpServer,
-      { task: "please pick this up", agentId: differentWorkerId, allowDuplicate: true },
+      {
+        task: "please pick this up",
+        agentId: differentWorkerId,
+        routingReason: "human_pinned",
+        allowDuplicate: true,
+      },
       leadAgentId,
       followUp.body.id,
     );

package/src/tests/workflow-agent-task.test.ts

@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import {
   closeDb,
+  createAgent,
   createWorkflow,
   createWorkflowRun,
   createWorkflowRunStep,
@@ -9,7 +10,7 @@ import {
   initDb,
 } from "../be/db";
 import type { ExecutorMeta } from "../types";
-import { AgentTaskExecutor } from "../workflows/executors/agent-task";
+import { AgentTaskConfigSchema, AgentTaskExecutor } from "../workflows/executors/agent-task";
 import type { ExecutorDependencies } from "../workflows/executors/base";
 
 const TEST_DB_PATH = "./test-workflow-agent-task.sqlite";
@@ -94,6 +95,20 @@ afterAll(async () => {
 // ─── Tests ───────────────────────────────────────────────────
 
 describe("AgentTaskExecutor — workspace scoping", () => {
+  test("existing configured agent pins accept optional routing metadata", () => {
+    expect(AgentTaskConfigSchema.safeParse({ template: "work", agentId: "worker" }).success).toBe(
+      true,
+    );
+    expect(
+      AgentTaskConfigSchema.safeParse({
+        template: "work",
+        agentId: "worker",
+        routingReason: "human_pinned",
+        routingNote: "workflow author chose this worker",
+      }).success,
+    ).toBe(true);
+  });
+
   test("config schema accepts dir, vcsRepo, model, modelTier, parentTaskId", () => {
     const executor = new AgentTaskExecutor(mockDeps);
     const config = {
@@ -146,7 +161,13 @@ describe("AgentTaskExecutor — workspace scoping", () => {
 
   test("execute() creates task with workspace fields forwarded", async () => {
     const executor = new AgentTaskExecutor(mockDeps);
+    const worker = await createAgent({
+      name: "Pinned workflow worker",
+      isLead: false,
+      status: "idle",
+    });
     const config = {
+      agentId: worker.id,
       template: "List files in workspace",
       dir: "/workspace/repos/agent-swarm",
       vcsRepo: "desplega-ai/agent-swarm",
@@ -173,6 +194,8 @@ describe("AgentTaskExecutor — workspace scoping", () => {
     expect(task!.model).toBeUndefined();
     expect(task!.modelTier).toBe("regular");
     expect(task!.source).toBe("workflow");
+    expect(task!.agentId).toBe(worker.id);
+    expect(task!.routingReason).toBe("human_pinned");
   });
 
   test("execute() creates task without workspace fields (backward compat)", async () => {

package/src/tests/workflow-engine-v2.test.ts

@@ -1,6 +1,17 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  setSystemTime,
+  spyOn,
+  test,
+} from "bun:test";
 import { unlink } from "node:fs/promises";
 import { z } from "zod";
+import * as preflightAlerts from "../automation-preflight-alert";
 import {
   closeDb,
   createWorkflow,
@@ -264,6 +275,21 @@ describe("Workflow Engine v2 (Phase 3)", () => {
   // ─── Linear Workflow ──────────────────────────────────────
 
   describe("Automation preflight", () => {
+    let notify: ReturnType<
+      typeof spyOn<typeof preflightAlerts, "notifyAutomationPreflightFailure">
+    >;
+
+    beforeEach(() => {
+      notify = spyOn(preflightAlerts, "notifyAutomationPreflightFailure").mockResolvedValue(
+        undefined,
+      );
+    });
+
+    afterEach(() => {
+      notify.mockRestore();
+      setSystemTime();
+    });
+
     test("records one failed run per workflow/day despite reason changes and creates no tasks", async () => {
       const registry = createTestRegistry();
       const workflow = await makeWorkflow(
@@ -285,7 +311,13 @@ describe("Workflow Engine v2 (Phase 3)", () => {
         finishedAt: new Date().toISOString(),
       });
 
-      const firstRunId = await startWorkflowExecution(workflow, {}, registry);
+      const firstRunId = await startWorkflowExecution(workflow, {}, registry, {
+        triggerType: "schedule",
+      });
+      expect(notify).toHaveBeenCalledTimes(1);
+      expect(notify).toHaveBeenCalledWith(
+        expect.objectContaining({ kind: "workflow", name: workflow.name, state: "needs_setup" }),
+      );
       const secondRunId = await startWorkflowExecution(
         { ...workflow, requiredParams: ["OTHER_PARAM"] },
         {},
@@ -297,6 +329,7 @@ describe("Workflow Engine v2 (Phase 3)", () => {
       );
 
       expect(secondRunId).toBe(firstRunId);
+      expect(notify).toHaveBeenCalledTimes(1);
       expect(firstRunId).not.toBe(ordinaryRunId);
       expect(run?.status).toBe("failed");
       expect(run?.error).toBe("needs_setup: params=[REPO_URL] integrations=[]");
@@ -312,6 +345,29 @@ describe("Workflow Engine v2 (Phase 3)", () => {
       ).toEqual({ total: 2, preflight: 1 });
     });
 
+    test("alerts once for concurrent workflow refusals and again after UTC midnight", async () => {
+      setSystemTime(new Date("2026-09-14T23:59:59Z"));
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow(
+        { nodes: [{ id: "start", type: "echo", config: { message: "{{REPO_URL}}" } }] },
+        { requiredParams: ["REPO_URL"] },
+      );
+      const [firstRunId, repeatedRunId] = await Promise.all([
+        startWorkflowExecution(workflow, {}, registry, { triggerType: "schedule" }),
+        startWorkflowExecution(workflow, {}, registry, { triggerType: "schedule" }),
+      ]);
+      expect(repeatedRunId).toBe(firstRunId);
+      expect(notify).toHaveBeenCalledTimes(1);
+
+      setSystemTime(new Date("2026-09-15T00:00:00Z"));
+      const nextRunId = await startWorkflowExecution(workflow, {}, registry, {
+        triggerType: "schedule",
+      });
+      expect(nextRunId).not.toBe(firstRunId);
+      expect(notify).toHaveBeenCalledTimes(2);
+      expect((await getWorkflowRun(nextRunId))?.error).toContain("needs_setup:");
+    });
+
     test("renders parameters across workflow runtime fields and preserves input value types", async () => {
       const registry = createTestRegistry();
       const workflow = await makeWorkflow(

package/src/tools/accept-steer.ts

@@ -16,7 +16,6 @@ export const acceptSteerInputSchema = z.object({
   steeringMessageId: z.uuid().describe("The steering message ID to acknowledge."),
   note: z
     .string()
-    .max(500)
     .optional()
     .describe("Optional short note describing how the steering was incorporated."),
 });