@desplega.ai/agent-swarm 1.86.0 → 1.87.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.86.0",
+    "version": "1.87.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -7139,6 +7139,16 @@
             "required": true,
             "name": "taskId",
             "in": "path"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1000
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
           }
         ],
         "responses": {
@@ -10114,6 +10124,67 @@
         }
       }
     },
+    "/api/tasks/{id}/supersede": {
+      "post": {
+        "summary": "Supersede an in-progress task (terminate + spawn resume follow-up)",
+        "description": "Marks the original task `superseded` (terminal) and creates a fresh `taskType=\"resume\"` follow-up so a worker can pick up the work in a new provider session. Workflow-step tasks (those with `workflowRunStepId`) are carved out: the original is marked `failed` with reason `superseded_workflow_task` and no follow-up is created — the workflow engine's retry/failure policy applies.",
+        "tags": [
+          "Tasks"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "reason": {
+                    "type": "string",
+                    "enum": [
+                      "graceful_shutdown",
+                      "context_limits",
+                      "manual_supersede",
+                      "crash_recovery"
+                    ]
+                  }
+                },
+                "required": [
+                  "reason"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Task superseded (or workflow-failed)"
+          },
+          "400": {
+            "description": "Task not in_progress"
+          },
+          "403": {
+            "description": "Task belongs to another agent"
+          },
+          "404": {
+            "description": "Task not found"
+          }
+        }
+      }
+    },
     "/api/tasks/{id}/vcs": {
       "patch": {
         "summary": "Update VCS (PR/MR) info for a task",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.86.0",
+  "version": "1.87.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -45,6 +45,7 @@
     "tsc:check": "bun tsc --noEmit",
     "check:db-boundary": "bash scripts/check-db-boundary.sh",
     "check:api-key-boundary": "bash scripts/check-api-key-boundary.sh",
+    "prepare-release": "bun scripts/prepare-release.ts",
     "sync-chart-version": "bun scripts/sync-chart-version.ts",
     "check-chart-version": "bun scripts/sync-chart-version.ts --check-if-package-version-changed",
     "cli": "bun src/cli.tsx",
@@ -130,6 +131,7 @@
     "ai": "^6.0.116",
     "cron-parser": "^5.4.0",
     "date-fns": "^4.1.0",
+    "e2b": "2.26.0",
     "hono": "^4.12.3",
     "ink": "^6.5.1",
     "oauth4webapi": "^3.8.5",

package/src/be/db-queries/tracker.ts

@@ -110,6 +110,27 @@ export function updateTrackerSyncSwarmId(id: string, swarmId: string): void {
   getDb().query("UPDATE tracker_sync SET swarmId = ? WHERE id = ?").run(swarmId, id);
 }
 
+/**
+ * Repoint ALL `tracker_sync` rows currently keyed to `oldSwarmId` to
+ * `newSwarmId`. Returns the number of rows updated.
+ *
+ * Used when a task is superseded (PR #594): the supersede parent becomes
+ * terminal but the Linear/Jira issue is still active, and outbound
+ * completion posts + inbound webhooks lookup by swarmId. Without
+ * repointing, the resume child's completion never makes it back to the
+ * tracker and subsequent inbound events load the terminal parent and
+ * create duplicates.
+ *
+ * Safe to call when no rows match (no-op, returns 0). Repoints across
+ * all providers (Linear AND Jira) and all entity types in one call.
+ */
+export function repointTrackerSyncBySwarmId(oldSwarmId: string, newSwarmId: string): number {
+  const result = getDb()
+    .query("UPDATE tracker_sync SET swarmId = ? WHERE swarmId = ?")
+    .run(newSwarmId, oldSwarmId);
+  return Number(result.changes ?? 0);
+}
+
 export function createTrackerSync(data: {
   provider: string;
   entityType: "task";

package/src/be/db.ts

@@ -29,6 +29,7 @@ import type {
   ContextSnapshotEventType,
   ContextVersion,
   CooldownConfig,
+  FollowUpConfig,
   InboxItemState,
   InboxItemStatus,
   InboxItemType,
@@ -87,6 +88,7 @@ import type {
   WorkflowSummary,
   WorkflowVersion,
 } from "../types";
+import { FollowUpConfigSchema, isTerminalTaskStatus } from "../types";
 import { deriveProviderFromKeyType } from "../utils/credentials";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { decryptSecret, encryptSecret, getEncryptionKey, resolveEncryptionKey } from "./crypto";
@@ -993,6 +995,7 @@ type AgentTaskRow = {
   workflowRunId: string | null;
   workflowRunStepId: string | null;
   outputSchema: string | null;
+  followUpConfig: string | null;
   contextKey: string | null;
   createdAt: string;
   lastUpdatedAt: string;
@@ -1016,6 +1019,27 @@ type AgentTaskRow = {
 };
 
 function rowToAgentTask(row: AgentTaskRow): AgentTask {
+  let followUpConfig: FollowUpConfig | undefined;
+  if (row.followUpConfig) {
+    try {
+      const parsed = FollowUpConfigSchema.safeParse(JSON.parse(row.followUpConfig));
+      if (parsed.success) {
+        followUpConfig = parsed.data;
+      } else {
+        console.warn(
+          `[db] Ignoring invalid agent_tasks.followUpConfig for task ${row.id}:`,
+          parsed.error.message,
+        );
+      }
+    } catch (error) {
+      console.warn(
+        `[db] Ignoring malformed agent_tasks.followUpConfig for task ${row.id}:`,
+        error instanceof Error ? error.message : String(error),
+      );
+      followUpConfig = undefined;
+    }
+  }
+
   return {
     id: row.id,
     agentId: row.agentId,
@@ -1057,6 +1081,7 @@ function rowToAgentTask(row: AgentTaskRow): AgentTask {
     workflowRunId: row.workflowRunId ?? undefined,
     workflowRunStepId: row.workflowRunStepId ?? undefined,
     outputSchema: row.outputSchema ? JSON.parse(row.outputSchema) : undefined,
+    followUpConfig,
     contextKey: row.contextKey ?? undefined,
     compactionCount: row.compactionCount ?? undefined,
     peakContextPercent: row.peakContextPercent ?? undefined,
@@ -1173,7 +1198,7 @@ export const taskQueries = {
   setProgress: () =>
     getDb().prepare<AgentTaskRow, [string, string]>(
       `UPDATE agent_tasks SET progress = ?,
-       status = CASE WHEN status IN ('completed', 'failed', 'cancelled') THEN status ELSE 'in_progress' END,
+       status = CASE WHEN status IN ('completed', 'failed', 'cancelled', 'superseded') THEN status ELSE 'in_progress' END,
        lastUpdatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
        WHERE id = ? RETURNING *`,
     ),
@@ -1244,14 +1269,14 @@ export function startTask(taskId: string): AgentTask | null {
   if (!oldTask) return null;
 
   // Guard: never revive tasks that are already in a terminal state
-  if (["completed", "failed", "cancelled"].includes(oldTask.status)) {
+  if (isTerminalTaskStatus(oldTask.status)) {
     return null;
   }
 
   const row = getDb()
     .prepare<AgentTaskRow, [string]>(
       `UPDATE agent_tasks SET status = 'in_progress', lastUpdatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
-       WHERE id = ? AND status NOT IN ('completed', 'failed', 'cancelled') RETURNING *`,
+       WHERE id = ? AND status NOT IN ('completed', 'failed', 'cancelled', 'superseded') RETURNING *`,
     )
     .get(taskId);
   if (row && oldTask) {
@@ -1291,6 +1316,31 @@ export function getChildTasks(parentTaskId: string): AgentTask[] {
     .map(rowToAgentTask);
 }
 
+/**
+ * Returns true if `parentId` has at least one non-terminal child task with
+ * `taskType = 'resume'`. Used by the heartbeat sweep as an idempotency guard:
+ * if a prior sweep tick already created a resume follow-up for this parent,
+ * don't create a duplicate.
+ *
+ * **Filters by taskType = 'resume'** specifically. A parent task can also
+ * have ordinary non-terminal delegation children (`send-task` auto-defaults
+ * `parentTaskId` to the caller's current task — see src/tools/send-task.ts).
+ * Treating those as "already resumed" would incorrectly skip the resume
+ * path for a crashed worker that had delegated subtasks (PR #594 review).
+ */
+export function hasNonTerminalResumeChild(parentId: string): boolean {
+  const row = getDb()
+    .prepare(
+      `SELECT 1 FROM agent_tasks
+       WHERE parentTaskId = ?
+         AND taskType = 'resume'
+         AND status NOT IN ('completed', 'failed', 'cancelled', 'superseded')
+       LIMIT 1`,
+    )
+    .get(parentId);
+  return row !== undefined && row !== null;
+}
+
 export function updateTaskClaudeSessionId(
   taskId: string,
   claudeSessionId: string,
@@ -1370,14 +1420,18 @@ export function getTasksByStatus(status: AgentTaskStatus): AgentTask[] {
 
 /**
  * Find a task by VCS repo and issue/PR/MR number.
- * Returns the most recent non-completed/failed task for this VCS entity.
+ * Returns the most recent non-terminal task for this VCS entity.
+ *
+ * Terminal exclusion MUST stay in lock-step with `TERMINAL_TASK_STATUSES`
+ * in `src/types.ts`. SQL strings can't import a TS const — if you add a
+ * new terminal status, grep for `NOT IN ('completed'` across this file.
  */
 export function findTaskByVcs(vcsRepo: string, vcsNumber: number): AgentTask | null {
   const row = getDb()
     .prepare<AgentTaskRow, [string, number]>(
       `SELECT * FROM agent_tasks
        WHERE vcsRepo = ? AND vcsNumber = ?
-       AND status NOT IN ('completed', 'failed')
+       AND status NOT IN ('completed', 'failed', 'cancelled', 'superseded')
        ORDER BY createdAt DESC
        LIMIT 1`,
     )
@@ -1926,7 +1980,7 @@ export function completeTask(id: string, output?: string): AgentTask | null {
   // Idempotency guard: don't re-complete a task already in a terminal state.
   // Mirrors cancelTask. Prevents duplicate task.completed events, duplicate
   // log entries, and duplicate follow-up tasks when multiple sessions race.
-  if (["completed", "failed", "cancelled"].includes(oldTask.status)) {
+  if (isTerminalTaskStatus(oldTask.status)) {
     return null;
   }
 
@@ -1971,7 +2025,7 @@ export function failTask(id: string, reason: string): AgentTask | null {
   // Idempotency guard: don't re-fail a task already in a terminal state.
   // Mirrors cancelTask / completeTask. Prevents duplicate task.failed events
   // and duplicate follow-up tasks when multiple sessions race.
-  if (["completed", "failed", "cancelled"].includes(oldTask.status)) {
+  if (isTerminalTaskStatus(oldTask.status)) {
     return null;
   }
 
@@ -2008,8 +2062,7 @@ export function cancelTask(id: string, reason?: string): AgentTask | null {
   if (!oldTask) return null;
 
   // Only cancel tasks that are not already in a terminal state
-  const terminalStatuses = ["completed", "failed", "cancelled"];
-  if (terminalStatuses.includes(oldTask.status)) {
+  if (isTerminalTaskStatus(oldTask.status)) {
     return null;
   }
 
@@ -2043,6 +2096,69 @@ export function cancelTask(id: string, reason?: string): AgentTask | null {
   return row ? rowToAgentTask(row) : null;
 }
 
+/**
+ * Supersede a task: mark it as `superseded` (terminal) so a fresh "resume"
+ * follow-up task can pick up where it left off. Used by the graceful-shutdown
+ * path and the `POST /api/tasks/:id/supersede` route. Returns null if the task
+ * is already terminal (mirrors `completeTask` / `cancelTask` idempotency).
+ *
+ * Writes a `task_superseded` agent_log with `{ reason, resumeTaskId }` payload
+ * and emits a `task.superseded` workflow event. The caller is responsible for
+ * creating the resume follow-up (via `createResumeFollowUp`) and passing the
+ * resulting id as `resumeTaskId`.
+ */
+export function supersedeTask(
+  id: string,
+  args: { reason: string; resumeTaskId: string | null },
+): AgentTask | null {
+  const oldTask = getTaskById(id);
+  if (!oldTask) return null;
+
+  // Idempotency guard: don't re-supersede a task already in a terminal state.
+  if (isTerminalTaskStatus(oldTask.status)) {
+    return null;
+  }
+
+  const finishedAt = new Date().toISOString();
+  const row = getDb()
+    .prepare<AgentTaskRow, [string, string]>(
+      `UPDATE agent_tasks
+       SET status = 'superseded',
+           finishedAt = ?,
+           lastUpdatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE id = ? AND status NOT IN ('completed', 'failed', 'cancelled', 'superseded')
+       RETURNING *`,
+    )
+    .get(finishedAt, id);
+
+  if (row && oldTask) {
+    try {
+      createLogEntry({
+        eventType: "task_superseded",
+        taskId: id,
+        agentId: row.agentId ?? undefined,
+        oldValue: oldTask.status,
+        newValue: "superseded",
+        metadata: { reason: args.reason, resumeTaskId: args.resumeTaskId },
+      });
+    } catch {}
+    try {
+      import("../workflows/event-bus").then(({ workflowEventBus }) => {
+        workflowEventBus.emit("task.superseded", {
+          taskId: id,
+          reason: args.reason,
+          resumeTaskId: args.resumeTaskId,
+          agentId: row.agentId,
+          workflowRunId: row.workflowRunId,
+          workflowRunStepId: row.workflowRunStepId,
+        });
+      });
+    } catch {}
+  }
+
+  return row ? rowToAgentTask(row) : null;
+}
+
 /**
  * Pause a task that is currently in progress.
  * Used during graceful shutdown to allow tasks to resume after container restart.
@@ -2560,6 +2676,7 @@ export interface CreateTaskOptions {
    * a schema'd task should be defensive about JSON parsing.
    */
   outputSchema?: Record<string, unknown>;
+  followUpConfig?: FollowUpConfig;
   requestedByUserId?: string;
   contextKey?: string;
 }
@@ -2578,8 +2695,9 @@ export function findRecentSimilarTasks(opts: {
   const conditions: string[] = ["createdAt > ?"];
   const params: (string | number)[] = [since];
 
-  // Exclude completed/failed/cancelled tasks — only active or recently created
-  conditions.push("status NOT IN ('completed', 'failed', 'cancelled')");
+  // Exclude all terminal statuses — only active or recently created.
+  // Keep in lock-step with `TERMINAL_TASK_STATUSES` in src/types.ts.
+  conditions.push("status NOT IN ('completed', 'failed', 'cancelled', 'superseded')");
 
   if (opts.creatorAgentId) {
     conditions.push("creatorAgentId = ?");
@@ -2614,6 +2732,16 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
   if (options?.parentTaskId) {
     const parent = getTaskById(options.parentTaskId);
     if (parent) {
+      // Identity & routing — anything that says "what work is this, who asked
+      // for it, where does it run" carries forward to every child (follow-ups,
+      // reboot retries, resume tasks). Explicit options always win.
+      //
+      // When adding a new identity-shaped column to `agent_tasks`, ADD IT HERE
+      // unless you have a specific reason a child should NOT inherit it. This
+      // is the single source of truth — `createResumeFollowUp` and the other
+      // follow-up creators rely on this block instead of re-listing fields.
+
+      // Slack context
       if (parent.slackChannelId && !options.slackChannelId) {
         options.slackChannelId = parent.slackChannelId;
       }
@@ -2623,18 +2751,98 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
       if (parent.slackUserId && !options.slackUserId) {
         options.slackUserId = parent.slackUserId;
       }
+
+      // AgentMail context
       if (parent.agentmailInboxId && !options.agentmailInboxId) {
         options.agentmailInboxId = parent.agentmailInboxId;
       }
+      if (parent.agentmailMessageId && !options.agentmailMessageId) {
+        options.agentmailMessageId = parent.agentmailMessageId;
+      }
       if (parent.agentmailThreadId && !options.agentmailThreadId) {
         options.agentmailThreadId = parent.agentmailThreadId;
       }
+
+      // Mention context (Slack @-mentions)
+      if (parent.mentionMessageId && !options.mentionMessageId) {
+        options.mentionMessageId = parent.mentionMessageId;
+      }
+      if (parent.mentionChannelId && !options.mentionChannelId) {
+        options.mentionChannelId = parent.mentionChannelId;
+      }
+
+      // VCS identity (GitHub / GitLab issue / PR / MR + webhook routing)
+      // Webhook handlers locate active work via `findTaskByVcs(repo, number)`,
+      // so a resume / follow-up child MUST carry the full VCS identity or
+      // subsequent review/update events get dropped.
+      if (parent.vcsProvider && !options.vcsProvider) {
+        options.vcsProvider = parent.vcsProvider;
+      }
+      if (parent.vcsRepo && !options.vcsRepo) {
+        options.vcsRepo = parent.vcsRepo;
+      }
+      if (parent.vcsNumber != null && options.vcsNumber == null) {
+        options.vcsNumber = parent.vcsNumber;
+      }
+      if (parent.vcsEventType && !options.vcsEventType) {
+        options.vcsEventType = parent.vcsEventType;
+      }
+      if (parent.vcsCommentId != null && options.vcsCommentId == null) {
+        options.vcsCommentId = parent.vcsCommentId;
+      }
+      if (parent.vcsAuthor && !options.vcsAuthor) {
+        options.vcsAuthor = parent.vcsAuthor;
+      }
+      if (parent.vcsUrl && !options.vcsUrl) {
+        options.vcsUrl = parent.vcsUrl;
+      }
+      if (parent.vcsInstallationId != null && options.vcsInstallationId == null) {
+        options.vcsInstallationId = parent.vcsInstallationId;
+      }
+      if (parent.vcsNodeId && !options.vcsNodeId) {
+        options.vcsNodeId = parent.vcsNodeId;
+      }
+
+      // Execution context (per-task overrides)
+      //
+      // `model` is DELIBERATELY NOT inherited. A parent task's `model` is a
+      // concrete, provider-specific resolved string (e.g. `claude-opus-4-8`,
+      // `openrouter/moonshotai/kimi-k2.6`). Derived tasks (resume follow-ups,
+      // completion/review follow-ups, re-dispatches) routinely land on a
+      // DIFFERENT agent — and therefore a different harness/provider — than the
+      // parent. Carrying the parent's concrete model across that boundary makes
+      // the child die at session-init with a model-incompatibility error before
+      // any worker code runs (e.g. a `claude-opus-4-8` resume claimed by a Codex
+      // worker → `400 model is not supported when using Codex`, or a
+      // `kimi-k2.6` review follow-up routed to a Claude-harness Lead → session
+      // exit 1). Per Taras's directive (2026-05-29): derived tasks must never
+      // set the model — it resolves from the ASSIGNEE agent's own provider /
+      // `MODEL_OVERRIDE` config at session-init (see
+      // `src/commands/runner.ts` — `opts.model || configModel`). A null `model`
+      // here is the correct, intended state. Do NOT re-add inheritance here; if
+      // a same-provider child genuinely needs a specific model, the creator must
+      // pass it explicitly.
+      if (parent.dir && !options.dir) {
+        options.dir = parent.dir;
+      }
+
+      // Contract (schema validation) — `store-progress` validates completion
+      // output against `outputSchema`, runner injects structured-output
+      // instructions only when it's present.
+      if (parent.outputSchema && !options.outputSchema) {
+        options.outputSchema = parent.outputSchema;
+      }
+
+      // Attribution
       if (parent.requestedByUserId && !options.requestedByUserId) {
         options.requestedByUserId = parent.requestedByUserId;
       }
       if (parent.contextKey && !options.contextKey) {
         options.contextKey = parent.contextKey;
       }
+      if (parent.followUpConfig && !options.followUpConfig) {
+        options.followUpConfig = parent.followUpConfig;
+      }
     }
   }
 
@@ -2660,8 +2868,8 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
         vcsInstallationId, vcsNodeId,
         agentmailInboxId, agentmailMessageId, agentmailThreadId,
         mentionMessageId, mentionChannelId, dir, parentTaskId, model, scheduleId,
-        workflowRunId, workflowRunStepId, outputSchema, requestedByUserId, contextKey, swarmVersion, createdAt, lastUpdatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+        workflowRunId, workflowRunStepId, outputSchema, followUpConfig, requestedByUserId, contextKey, swarmVersion, createdAt, lastUpdatedAt
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
     )
     .get(
       id,
@@ -2700,6 +2908,7 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
       options?.workflowRunId ?? null,
       options?.workflowRunStepId ?? null,
       options?.outputSchema ? JSON.stringify(options.outputSchema) : null,
+      options?.followUpConfig ? JSON.stringify(options.followUpConfig) : null,
       options?.requestedByUserId ?? null,
       options?.contextKey ?? null,
       pkg.version,
@@ -4017,6 +4226,15 @@ export const sessionLogQueries = {
       "SELECT * FROM session_logs WHERE taskId = ? ORDER BY iteration ASC, lineNumber ASC",
     ),
 
+  getRecentByTaskId: () =>
+    getDb().prepare<SessionLogRow, [string, number]>(
+      `SELECT * FROM (
+         SELECT * FROM session_logs WHERE taskId = ?
+         ORDER BY iteration DESC, lineNumber DESC
+         LIMIT ?
+       ) ORDER BY iteration ASC, lineNumber ASC`,
+    ),
+
   getBySessionId: () =>
     getDb().prepare<SessionLogRow, [string, number]>(
       "SELECT * FROM session_logs WHERE sessionId = ? AND iteration = ? ORDER BY lineNumber ASC",
@@ -4052,7 +4270,10 @@ export function createSessionLogs(logs: {
   })();
 }
 
-export function getSessionLogsByTaskId(taskId: string): SessionLog[] {
+export function getSessionLogsByTaskId(taskId: string, limit?: number): SessionLog[] {
+  if (typeof limit === "number" && limit > 0) {
+    return sessionLogQueries.getRecentByTaskId().all(taskId, limit).map(rowToSessionLog);
+  }
   return sessionLogQueries.getByTaskId().all(taskId).map(rowToSessionLog);
 }
 

package/src/be/migrations/079_task_followup_config.sql

@@ -0,0 +1 @@
+ALTER TABLE agent_tasks ADD COLUMN followUpConfig TEXT;