@desplega.ai/agent-swarm 1.86.0 → 1.87.0

package/src/tests/telemetry-init.test.ts

@@ -17,6 +17,7 @@ describe("initTelemetry", () => {
     // Tests below set MCP_BASE_URL to assert classification — clear between
     // tests so cases that expect "unset" don't inherit a prior test's value.
     delete process.env.MCP_BASE_URL;
+    delete process.env.DESPLEGA_TELEMETRY_ENV;
   });
 
   test("without generateIfMissing + missing config → installationId stays null (track no-ops)", async () => {
@@ -390,4 +391,72 @@ describe("initTelemetry", () => {
       expect(properties.is_cloud).toBe(true);
     });
   });
+
+  describe("track() metadata.environment", () => {
+    const originalFetch = globalThis.fetch;
+    const originalNodeEnv = process.env.NODE_ENV;
+    let captured: Record<string, unknown> | null = null;
+
+    beforeEach(() => {
+      captured = null;
+      globalThis.fetch = (async (_url: string, init?: { body?: string }) => {
+        captured = init?.body ? JSON.parse(init.body) : null;
+        return new Response(null, { status: 204 });
+      }) as typeof fetch;
+      delete process.env.DESPLEGA_TELEMETRY_ENV;
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+      delete process.env.DESPLEGA_TELEMETRY_ENV;
+      if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+      else process.env.NODE_ENV = originalNodeEnv;
+    });
+
+    test("defaults to production even when NODE_ENV is development", async () => {
+      process.env.NODE_ENV = "development";
+      await initTelemetry(
+        "api-server",
+        async () => "install_default_env",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.environment).toBe("production");
+    });
+
+    test("uses DESPLEGA_TELEMETRY_ENV when set", async () => {
+      process.env.NODE_ENV = "production";
+      process.env.DESPLEGA_TELEMETRY_ENV = "development";
+      await initTelemetry(
+        "api-server",
+        async () => "install_explicit_env",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.environment).toBe("development");
+    });
+
+    test("preserves NODE_ENV=test when telemetry env is unset", async () => {
+      process.env.NODE_ENV = "test";
+      await initTelemetry(
+        "api-server",
+        async () => "install_test_env",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.environment).toBe("test");
+    });
+  });
 });

package/src/tests/vcs-tracking.test.ts

@@ -1,11 +1,16 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import {
+  cancelTask,
   closeDb,
+  completeTask,
   createAgent,
   createTaskExtended,
+  failTask,
   findTaskByVcs,
   initDb,
+  startTask,
+  supersedeTask,
   updateTaskVcs,
 } from "../be/db";
 
@@ -133,6 +138,40 @@ describe("updateTaskVcs", () => {
     expect(found!.id).toBe(task.id);
   });
 
+  test("findTaskByVcs excludes ALL terminal statuses (completed, failed, cancelled, superseded)", () => {
+    // PR #594 review: missing `cancelled` / `superseded` in the filter
+    // meant webhooks for a terminated PR/MR still routed to the dead task.
+    // Guard against any one of the four terminal statuses being missed.
+    const TERMINAL_CASES = [
+      { name: "completed", number: 200, terminate: (id: string) => completeTask(id, "done") },
+      { name: "failed", number: 201, terminate: (id: string) => failTask(id, "boom") },
+      { name: "cancelled", number: 202, terminate: (id: string) => cancelTask(id) },
+      {
+        name: "superseded",
+        number: 203,
+        terminate: (id: string) =>
+          supersedeTask(id, { reason: "manual_supersede", resumeTaskId: null }),
+      },
+    ];
+    for (const c of TERMINAL_CASES) {
+      const task = createTaskExtended(`Terminal=${c.name}`, {
+        agentId: "vcs-track-agent-001",
+        source: "api",
+      });
+      updateTaskVcs(task.id, {
+        vcsProvider: "github",
+        vcsRepo: "owner/terminal",
+        vcsNumber: c.number,
+        vcsUrl: `https://github.com/owner/terminal/pull/${c.number}`,
+      });
+      startTask(task.id);
+      c.terminate(task.id);
+
+      const found = findTaskByVcs("owner/terminal", c.number);
+      expect(found).toBeNull();
+    }
+  });
+
   test("idempotent: calling twice with same data both succeed", () => {
     const task = createTaskExtended("Test idempotency", {
       agentId: "vcs-track-agent-001",

package/src/tools/send-task.ts

@@ -14,7 +14,7 @@ import {
 import { findDuplicateTask } from "@/tools/task-dedup";
 import { ownerCtx, type ToolCtx } from "@/tools/task-tool-ctx";
 import { createToolRegistrar } from "@/tools/utils";
-import { AgentTaskSchema } from "@/types";
+import { AgentTaskSchema, FollowUpConfigSchema } from "@/types";
 
 export const sendTaskInputSchema = z.object({
   agentId: z
@@ -83,6 +83,9 @@ export const sendTaskInputSchema = z.object({
     .describe(
       "ID of the human user who originally requested this task chain. When omitted, inherited from the caller's current task so the attribution flows through multi-hop delegation automatically.",
     ),
+  followUpConfig: FollowUpConfigSchema.optional().describe(
+    "Control the lead follow-up created when this task finishes. When to use `followUpConfig`: set `disabled: true` when you'll wait for this task to complete inline and no follow-up is needed; set `onCompleted` / `onFailed` with specific instructions when you need to follow up effectively on a particular outcome of a long-running flow; for normal one-shot tasks, leave it unset because defaults are fine. It is most valuable for long-running / complex flows.",
+  ),
 });
 
 export const sendTaskOutputSchema = z.object({
@@ -113,6 +116,7 @@ export async function sendTaskHandler(
     slackThreadTs,
     slackUserId,
     requestedByUserId: inputRequestedByUserId,
+    followUpConfig,
   }: SendTaskArgs,
 ): Promise<CallToolResult> {
   if (ctx.kind === "owner" && !ctx.agentId) {
@@ -200,6 +204,10 @@ export async function sendTaskHandler(
   // interrupted — re-dispatch is the correct response, not a deduped no-op.
   // Without this bypass, a cancelled worker permanently jams the thread
   // against re-delegation when an earlier completed sibling exists.
+  //
+  // NOTE: `taskType === "resume"` (created by createResumeFollowUp on
+  // supersede) is intentionally NOT in this guard — a resume IS the legitimate
+  // re-dispatch and bypassing the check is correct. Do not add "resume" here.
   if (sourceTaskId) {
     const sourceTask = getTaskById(sourceTaskId);
     if (
@@ -259,6 +267,7 @@ export async function sendTaskHandler(
         slackChannelId,
         slackThreadTs,
         slackUserId,
+        followUpConfig,
       });
 
       return {
@@ -311,6 +320,7 @@ export async function sendTaskHandler(
         slackChannelId,
         slackThreadTs,
         slackUserId,
+        followUpConfig,
       });
 
       return {
@@ -337,6 +347,7 @@ export async function sendTaskHandler(
       slackChannelId,
       slackThreadTs,
       slackUserId,
+      followUpConfig,
     });
 
     return {

package/src/tools/store-progress.ts

@@ -18,7 +18,7 @@ import { getRetrievalsForTask } from "@/be/memory/raters/retrieval";
 import { runServerRaters } from "@/be/memory/raters/run-server-raters";
 import { createWorkerTaskFollowUp } from "@/tasks/worker-follow-up";
 import { createToolRegistrar } from "@/tools/utils";
-import { AgentTaskSchema, AttachmentInputSchema } from "@/types";
+import { AgentTaskSchema, AttachmentInputSchema, isTerminalTaskStatus } from "@/types";
 import { validateJsonSchema } from "@/workflows/json-schema-validator";
 
 // Phase 11: the `cost` / `costData` field was removed from this tool's input
@@ -115,7 +115,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         }
 
         let updatedTask = existingTask;
-        const isTerminal = ["completed", "failed", "cancelled"].includes(existingTask.status);
+        const isTerminal = isTerminalTaskStatus(existingTask.status);
 
         // Attachments — pointer-based, append-only. Insert each row inside
         // this transaction; the helper dedups by sha256 (when present) or by

package/src/tools/templates.ts

@@ -52,10 +52,11 @@ registerTemplate({
   defaultBody: `Worker task completed \u2014 review needed.
 
 Agent: {{agent_name}}
+Original task created by agent {{creator_agent}}
 Task: "{{task_desc}}"
 
 Output:
-{{output_summary}}
+{{output_summary}}{{follow_up_instructions}}
 
 IMPORTANT: Do NOT re-delegate or re-answer the original request. The worker has already handled it. Your job is ONLY to:
 1. Review the output above
@@ -65,8 +66,13 @@ IMPORTANT: Do NOT re-delegate or re-answer the original request. The worker has
 Use \`get-task-details\` with taskId "{{task_id}}" for full details.`,
   variables: [
     { name: "agent_name", description: "Worker agent name or ID prefix" },
+    { name: "creator_agent", description: "Agent ID that originally created the worker task" },
     { name: "task_desc", description: "Task description (truncated to 200 chars)" },
     { name: "output_summary", description: "Task output (truncated to 500 chars)" },
+    {
+      name: "follow_up_instructions",
+      description: "Optional per-task instructions from followUpConfig for this completion",
+    },
     { name: "task_id", description: "Original task ID" },
   ],
   category: "task_lifecycle",
@@ -106,15 +112,21 @@ registerTemplate({
   defaultBody: `Worker task failed \u2014 action needed.
 
 Agent: {{agent_name}}
+Original task created by agent {{creator_agent}}
 Task: "{{task_desc}}"
 
-Failure reason: {{failure_reason}}
+Failure reason: {{failure_reason}}{{follow_up_instructions}}
 
 Decide whether to reassign, retry, or handle the failure. Use \`get-task-details\` with taskId "{{task_id}}" for full details.`,
   variables: [
     { name: "agent_name", description: "Worker agent name or ID prefix" },
+    { name: "creator_agent", description: "Agent ID that originally created the worker task" },
     { name: "task_desc", description: "Task description (truncated to 200 chars)" },
     { name: "failure_reason", description: "Failure reason text" },
+    {
+      name: "follow_up_instructions",
+      description: "Optional per-task instructions from followUpConfig for this failure",
+    },
     { name: "task_id", description: "Original task ID" },
   ],
   category: "task_lifecycle",

package/src/types.ts

@@ -8,12 +8,36 @@ export const AgentTaskStatusSchema = z.enum([
   "reviewing", // Agent is reviewing an offered task
   "pending", // Assigned/accepted, waiting to start
   "in_progress",
-  "paused", // Interrupted by graceful shutdown, can resume
+  "paused", // Interrupted by graceful shutdown (legacy), can resume
   "completed",
   "failed",
   "cancelled", // Task was cancelled by lead or creator
+  "superseded", // Original terminated, replaced by a follow-up "resume" task
 ]);
 
+/**
+ * Terminal task statuses — a task in one of these is done. No further state
+ * transitions, no re-assignment, no follow-up creation on the same id.
+ *
+ * Single source of truth for JS-side checks (sync handlers, store-progress,
+ * db mutator guards, HTTP cancel guard).
+ *
+ * **SQL drift watch**: `src/be/db.ts` has ~8 prepared statements that inline
+ * these strings — SQL can't import a TS const. When adding a new terminal
+ * status, grep across `src/be/db.ts` for:
+ *   - `status NOT IN ('completed'` — non-terminal filters (findTaskByVcs,
+ *     findRecentSimilarTasks, mutator guards, hasNonTerminalChildTask)
+ *   - `status IN ('completed', 'failed'` — intent-terminal lookups
+ *   - `status = CASE WHEN status IN ('completed'` — setProgress guard
+ * and update every site.
+ */
+export const TERMINAL_TASK_STATUSES = ["completed", "failed", "cancelled", "superseded"] as const;
+export type TerminalTaskStatus = (typeof TERMINAL_TASK_STATUSES)[number];
+
+export function isTerminalTaskStatus(status: string): status is TerminalTaskStatus {
+  return (TERMINAL_TASK_STATUSES as readonly string[]).includes(status);
+}
+
 // ============================================================================
 // Lead Inbox Types
 // ============================================================================
@@ -103,6 +127,13 @@ export type ProviderMetaMap = {
   opencode: NoProviderMeta;
 };
 
+export const FollowUpConfigSchema = z.object({
+  disabled: z.boolean().optional(),
+  onCompleted: z.string().max(4000).optional(),
+  onFailed: z.string().max(4000).optional(),
+});
+export type FollowUpConfig = z.infer<typeof FollowUpConfigSchema>;
+
 export const AgentTaskSchema = z.object({
   id: z.uuid(),
   agentId: z.uuid().nullable(), // Nullable for unassigned tasks
@@ -186,6 +217,9 @@ export const AgentTaskSchema = z.object({
   // Structured output schema (optional — JSON Schema that task output must conform to)
   outputSchema: z.record(z.string(), z.unknown()).optional(),
 
+  // Lead follow-up control (optional — null/undefined preserves default behavior)
+  followUpConfig: FollowUpConfigSchema.optional(),
+
   // Pause tracking
   wasPaused: z.boolean().default(false),
 
@@ -660,7 +694,18 @@ export const AgentLogEventTypeSchema = z.enum([
   "budget.deleted",
   "pricing.inserted",
   "pricing.deleted",
+  // Graceful pause/resume via follow-up
+  "task_superseded",
+]);
+
+// Reasons a task can be superseded (terminal) and replaced by a "resume" follow-up.
+export const ResumeReasonSchema = z.enum([
+  "graceful_shutdown", // Worker received SIGTERM / SIGINT
+  "context_limits", // Provider session approaching context-window limits (Phase 6)
+  "manual_supersede", // Operator-triggered (e.g. dashboard button)
+  "crash_recovery", // Heartbeat sweep detected dead/stalled worker (DES-523)
 ]);
+export type ResumeReason = z.infer<typeof ResumeReasonSchema>;
 
 export const AgentLogSchema = z.object({
   id: z.uuid(),

package/src/workflows/executors/agent-task.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { workflowContextKey } from "../../tasks/context-key";
 import { withSiblingAwareness } from "../../tasks/sibling-awareness";
 import type { ExecutorMeta } from "../../types";
+import { FollowUpConfigSchema } from "../../types";
 import type { ExecutorResult } from "./base";
 import { BaseExecutor } from "./base";
 
@@ -18,6 +19,7 @@ const AgentTaskConfigSchema = z.object({
   model: z.string().min(1).optional(),
   parentTaskId: z.string().uuid().optional(),
   outputSchema: z.record(z.string(), z.unknown()).optional(),
+  followUpConfig: FollowUpConfigSchema.optional(),
 });
 
 const AgentTaskOutputSchema = z.object({
@@ -94,6 +96,7 @@ export class AgentTaskExecutor extends BaseExecutor<
         model: config.model,
         parentTaskId: config.parentTaskId,
         outputSchema: config.outputSchema,
+        followUpConfig: config.followUpConfig,
         contextKey: workflowContextKey({ workflowRunId: meta.runId }),
       },
     );