@desplega.ai/agent-swarm 1.53.0 → 1.53.1

package/README.md

@@ -58,6 +58,8 @@ Agent Swarm lets you run a team of AI coding agents that coordinate autonomously
 - **Onboarding wizard** — Interactive CLI wizard (`agent-swarm onboard`) to set up a new swarm from scratch with presets, credential collection, and docker-compose generation
 - **Skill system** — Reusable procedural knowledge: create, install, publish, and sync skills from GitHub with scope resolution (agent → swarm → global)
 - **Human-in-the-Loop** — Workflow nodes that pause for human approval or input, with a dashboard UI for reviewing and responding to requests
+- **MCP server management** — Register, install, and manage MCP servers for agents with scope cascade (agent → swarm → global) and auto-injection into worker containers
+- **Context usage tracking** — Monitor context window utilization and compaction events per task with visual indicators in the dashboard
 
 ## Quick Start
 

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.52.1",
+    "version": "1.53.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": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.53.0",
+  "version": "1.53.1",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/plugin/commands/work-on-task.md

@@ -21,11 +21,17 @@ Once you have the task details, you should:
    - Use `memory-get` on any highly relevant results to get full details
    - This step is NOT optional. Past learnings compound your effectiveness.
 <!-- /claude-only -->
-2. Figure out if you need to use any of the available commands to help you with your work (see below for available commands)
-2. Use the `/todos` command to add a new todo item indicating you are starting to work on the task (e.g. "Work on task XXX: <short description>"). This will help on restarts, as it will be easier to remember what you were doing.
-3. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah". Additionally use `/swarm-chat` command to notify the swarm, human and lead when applicable. Do not be too verbose, nor spammy.
-4. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
-5. Once you either done or in a dead-end, see the "Completion" section below.
+2. **Check Installed Skills (REQUIRED):** Before researching or implementing, review your "Installed Skills" section in the system prompt:
+   - If any skill's description or trigger matches this task, invoke it via the `Skill` tool BEFORE doing manual research
+   - Skills contain pre-built, tested procedures that save context window and cost
+   - Example: task involves Linear → use `linear-interaction` skill, task involves email → use `agentmail-sending` skill
+   - Only proceed to manual research/web search if NO installed skill covers the task
+   - This step is NOT optional. Skipping it wastes context and money.
+3. Figure out if you need to use any of the available commands to help you with your work (see below for available commands)
+4. Use the `/todos` command to add a new todo item indicating you are starting to work on the task (e.g. "Work on task XXX: <short description>"). This will help on restarts, as it will be easier to remember what you were doing.
+5. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah". Additionally use `/swarm-chat` command to notify the swarm, human and lead when applicable. Do not be too verbose, nor spammy.
+6. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
+7. Once you either done or in a dead-end, see the "Completion" section below.
 
 ### Available commands
 

package/plugin/pi-skills/work-on-task/SKILL.md

@@ -13,11 +13,17 @@ Once you get a task assigned, you need to immediately start working on it. To do
 
 Once you have the task details, you should:
 
-1. Figure out if you need to perform any research or planning before starting (see below)
-2. Use the `/skill:todos` to add a new todo item indicating you are starting to work on the task (e.g. "Work on task XXX: <short description>"). This will help on restarts, as it will be easier to remember what you were doing.
-3. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah". Additionally use `/skill:swarm-chat` to notify the swarm, human and lead when applicable. Do not be too verbose, nor spammy.
-4. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
-5. Once you either done or in a dead-end, see the "Completion" section below.
+1. **Check Installed Skills (REQUIRED):** Before researching or implementing, review your "Installed Skills" section in the system prompt:
+   - If any skill's description or trigger matches this task, invoke it via the `Skill` tool BEFORE doing manual research
+   - Skills contain pre-built, tested procedures that save context window and cost
+   - Example: task involves Linear → use `linear-interaction` skill, task involves email → use `agentmail-sending` skill
+   - Only proceed to manual research/web search if NO installed skill covers the task
+   - This step is NOT optional. Skipping it wastes context and money.
+2. Figure out if you need to perform any research or planning before starting (see below)
+3. Use the `/skill:todos` to add a new todo item indicating you are starting to work on the task (e.g. "Work on task XXX: <short description>"). This will help on restarts, as it will be easier to remember what you were doing.
+4. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah". Additionally use `/skill:swarm-chat` to notify the swarm, human and lead when applicable. Do not be too verbose, nor spammy.
+5. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
+6. Once you either done or in a dead-end, see the "Completion" section below.
 
 ### Research and Planning
 

package/src/be/db.ts

@@ -7855,6 +7855,13 @@ export function createContextSnapshot(input: CreateContextSnapshotInput): Contex
       .run(input.contextPercent, input.taskId);
   }
 
+  // Keep totalContextTokensUsed up to date with the latest known value
+  if (input.contextUsedTokens != null) {
+    getDb()
+      .prepare("UPDATE agent_tasks SET totalContextTokensUsed = ? WHERE id = ?")
+      .run(input.contextUsedTokens, input.taskId);
+  }
+
   if (input.eventType === "compaction") {
     getDb()
       .prepare(
@@ -7863,13 +7870,10 @@ export function createContextSnapshot(input: CreateContextSnapshotInput): Contex
       .run(input.taskId);
   }
 
-  if (input.eventType === "completion") {
+  if (input.eventType === "completion" && input.contextTotalTokens != null) {
     getDb()
-      .prepare(
-        `UPDATE agent_tasks SET totalContextTokensUsed = ?, contextWindowSize = ?
-         WHERE id = ?`,
-      )
-      .run(input.contextUsedTokens ?? null, input.contextTotalTokens ?? null, input.taskId);
+      .prepare("UPDATE agent_tasks SET contextWindowSize = ? WHERE id = ?")
+      .run(input.contextTotalTokens, input.taskId);
   }
 
   return {

package/src/linear/sync.ts

@@ -271,18 +271,40 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
 
   // Check if we already track this issue
   const existing = getTrackerSyncByExternalId("linear", "task", issueId);
+  const sessionId = agentSession ? String(agentSession.id ?? "") : "";
+
   if (existing) {
+    const existingTask = getTaskById(existing.swarmId);
+
+    // If the task is still active, acknowledge the new session but don't create a duplicate
+    if (existingTask && !["completed", "failed", "cancelled"].includes(existingTask.status)) {
+      console.log(
+        `[Linear Sync] Issue ${issueIdentifier} already tracked as active task ${existing.swarmId}, skipping`,
+      );
+      if (sessionId) {
+        taskSessionMap.set(existingTask.id, sessionId);
+        acknowledgeAgentSession(
+          sessionId,
+          `This issue is already being worked on (task ${existing.swarmId}).`,
+        ).catch((err) => {
+          console.error("[Linear Sync] Failed to acknowledge duplicate AgentSession:", err);
+        });
+      }
+      return;
+    }
+
+    // Task is done/failed/cancelled — create a follow-up task below
     console.log(
-      `[Linear Sync] Issue ${issueIdentifier} already tracked as task ${existing.swarmId}, skipping`,
+      `[Linear Sync] Issue ${issueIdentifier} was tracked as ${existingTask?.status ?? "unknown"} task ${existing.swarmId}, creating follow-up`,
     );
-    return;
   }
 
   const lead = findLeadAgent();
 
   const sessionSection = sessionUrl ? `\nSession: ${sessionUrl}` : "";
   const descriptionSection = issueDescription ? `\nDescription:\n${issueDescription}\n` : "";
-  const assignedResult = resolveTemplate("linear.issue.assigned", {
+  const templateName = existing ? "linear.issue.reassigned" : "linear.issue.assigned";
+  const templateResult = resolveTemplate(templateName, {
     issue_identifier: issueIdentifier,
     issue_title: issueTitle,
     issue_url: issueUrl,
@@ -290,16 +312,21 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
     description_section: descriptionSection,
   });
 
-  if (assignedResult.skipped) {
+  if (templateResult.skipped) {
     return;
   }
 
-  const task = createTaskExtended(assignedResult.text, {
+  const task = createTaskExtended(templateResult.text, {
     agentId: lead?.id ?? "",
     source: "linear",
     taskType: "linear-issue",
   });
 
+  // Delete old tracker_sync before creating new one (UNIQUE constraint)
+  if (existing) {
+    deleteTrackerSync(existing.id);
+  }
+
   createTrackerSync({
     provider: "linear",
     entityType: "task",
@@ -313,15 +340,14 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
   });
 
   // Track the AgentSession so outbound sync can post activities to it
-  const sessionId = agentSession ? String(agentSession.id ?? "") : "";
   if (sessionId) {
     taskSessionMap.set(task.id, sessionId);
 
     // Acknowledge the AgentSession (pending → active)
-    acknowledgeAgentSession(
-      sessionId,
-      `Task received by Agent Swarm (${task.id}). Processing...`,
-    ).catch((err) => {
+    const ackMsg = existing
+      ? `Follow-up task created (${task.id}). Previous task was ${existing.swarmId}. Processing...`
+      : `Task received by Agent Swarm (${task.id}). Processing...`;
+    acknowledgeAgentSession(sessionId, ackMsg).catch((err) => {
       console.error("[Linear Sync] Failed to acknowledge AgentSession:", err);
     });
 
@@ -336,8 +362,9 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
     }
   }
 
+  const action = existing ? "follow-up" : "new";
   console.log(
-    `[Linear Sync] Created task ${task.id} for ${issueIdentifier} -> ${lead?.name ?? "unassigned"}`,
+    `[Linear Sync] Created ${action} task ${task.id} for ${issueIdentifier} -> ${lead?.name ?? "unassigned"}`,
   );
 }
 

package/src/linear/templates.ts

@@ -27,6 +27,23 @@ URL: {{issue_url}}{{session_section}}
   category: "event",
 });
 
+registerTemplate({
+  eventType: "linear.issue.reassigned",
+  header: "[Linear {{issue_identifier}}] Re-assigned: {{issue_title}}",
+  defaultBody: `Source: Linear (Agent Session re-assignment)
+URL: {{issue_url}}{{session_section}}
+{{description_section}}
+This issue was previously tracked but the original task has completed. A new task has been created to handle the re-assignment.`,
+  variables: [
+    { name: "issue_identifier", description: "Linear issue identifier (e.g. ENG-123)" },
+    { name: "issue_title", description: "Issue title" },
+    { name: "issue_url", description: "Issue URL on Linear" },
+    { name: "session_section", description: "Session URL line or empty string" },
+    { name: "description_section", description: "Description section or empty string" },
+  ],
+  category: "event",
+});
+
 registerTemplate({
   eventType: "linear.issue.followup",
   header: "[Linear {{issue_identifier}}] Follow-up: {{issue_title}}",

package/src/tests/context-snapshot.test.ts

@@ -0,0 +1,127 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  closeDb,
+  createAgent,
+  createContextSnapshot,
+  createTaskExtended,
+  getContextSnapshotsByTaskId,
+  getContextSummaryByTaskId,
+  initDb,
+} from "../be/db";
+
+const TEST_DB_PATH = "./test-context-snapshot.sqlite";
+
+describe("Context Snapshots", () => {
+  const agentId = "aaaa0000-0000-4000-8000-000000000001";
+  const sessionId = "sess-001";
+  let taskId: string;
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {
+        // File doesn't exist
+      }
+    }
+
+    initDb(TEST_DB_PATH);
+    createAgent({ id: agentId, name: "Test Worker", isLead: false, status: "idle" });
+    const task = createTaskExtended("Test task for context snapshots", {
+      agentId,
+      source: "mcp",
+    });
+    taskId = task.id;
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  test("completion snapshot without contextUsedTokens preserves last known usage", () => {
+    // Simulate progress snapshots during task execution
+    createContextSnapshot({
+      taskId,
+      agentId,
+      sessionId,
+      eventType: "progress",
+      contextUsedTokens: 50000,
+      contextTotalTokens: 200000,
+      contextPercent: 25,
+    });
+
+    createContextSnapshot({
+      taskId,
+      agentId,
+      sessionId,
+      eventType: "progress",
+      contextUsedTokens: 80000,
+      contextTotalTokens: 200000,
+      contextPercent: 40,
+    });
+
+    // Simulate completion snapshot — runner doesn't have contextUsedTokens at session end
+    createContextSnapshot({
+      taskId,
+      agentId,
+      sessionId,
+      eventType: "completion",
+      // No contextUsedTokens or contextPercent — this is the bug scenario
+      contextTotalTokens: 200000,
+      cumulativeInputTokens: 100000,
+      cumulativeOutputTokens: 20000,
+    });
+
+    // The summary should preserve the last known context usage, not null/0
+    const summary = getContextSummaryByTaskId(taskId);
+    expect(summary.totalContextTokensUsed).toBe(80000);
+    expect(summary.contextWindowSize).toBe(200000);
+    expect(summary.peakContextPercent).toBe(40);
+  });
+
+  test("completion snapshot with contextUsedTokens uses provided value", () => {
+    // Create a second task for an isolated test
+    const task2 = createTaskExtended("Test task 2", { agentId, source: "mcp" });
+
+    createContextSnapshot({
+      taskId: task2.id,
+      agentId,
+      sessionId,
+      eventType: "progress",
+      contextUsedTokens: 50000,
+      contextTotalTokens: 200000,
+      contextPercent: 25,
+    });
+
+    // Completion with explicit contextUsedTokens should use that value
+    createContextSnapshot({
+      taskId: task2.id,
+      agentId,
+      sessionId,
+      eventType: "completion",
+      contextUsedTokens: 60000,
+      contextTotalTokens: 200000,
+      contextPercent: 30,
+    });
+
+    const summary = getContextSummaryByTaskId(task2.id);
+    expect(summary.totalContextTokensUsed).toBe(60000);
+    expect(summary.contextWindowSize).toBe(200000);
+  });
+
+  test("snapshots are returned in chronological order", () => {
+    const snapshots = getContextSnapshotsByTaskId(taskId);
+    expect(snapshots.length).toBe(3);
+    expect(snapshots[0].eventType).toBe("progress");
+    expect(snapshots[1].eventType).toBe("progress");
+    expect(snapshots[2].eventType).toBe("completion");
+  });
+});

package/src/tests/linear-webhook.test.ts

@@ -207,7 +207,7 @@ describe("handleAgentSessionEvent", () => {
     expect(task!.task).toContain("Fix login bug");
   });
 
-  test("skips duplicate issue (already tracked)", async () => {
+  test("skips when already-tracked issue has an active task", async () => {
     const event = {
       type: "AgentSession",
       action: "create",
@@ -221,11 +221,112 @@ describe("handleAgentSessionEvent", () => {
       },
     };
 
-    // Should not throw or create a second tracker_sync
+    // The task from the previous test is still pending (active)
+    const syncBefore = getTrackerSyncByExternalId("linear", "task", "issue-agent-session-001");
+    expect(syncBefore).not.toBeNull();
+    const originalSwarmId = syncBefore!.swarmId;
+
     await handleAgentSessionEvent(event);
-    // Just verify it didn't throw — the existing sync is still there
-    const sync = getTrackerSyncByExternalId("linear", "task", "issue-agent-session-001");
+
+    // Sync should still point to the same task (no follow-up created)
+    const syncAfter = getTrackerSyncByExternalId("linear", "task", "issue-agent-session-001");
+    expect(syncAfter).not.toBeNull();
+    expect(syncAfter!.swarmId).toBe(originalSwarmId);
+  });
+
+  test("creates follow-up task when already-tracked issue has a completed task", async () => {
+    // Create a task and tracker_sync, then mark the task as completed
+    const originalTask = createTaskExtended("Original linear task", {
+      source: "linear",
+      taskType: "linear-issue",
+    });
+    const { getDb } = await import("../be/db");
+    getDb().query("UPDATE agent_tasks SET status = 'completed' WHERE id = ?").run(originalTask.id);
+
+    createTrackerSync({
+      provider: "linear",
+      entityType: "task",
+      providerEntityType: "Issue",
+      swarmId: originalTask.id,
+      externalId: "issue-followup-completed-001",
+      externalIdentifier: "ENG-150",
+      externalUrl: "https://linear.app/team/issue/ENG-150",
+      lastSyncOrigin: "external",
+      syncDirection: "inbound",
+    });
+
+    const event = {
+      type: "AgentSession",
+      action: "create",
+      data: {
+        issue: {
+          id: "issue-followup-completed-001",
+          identifier: "ENG-150",
+          title: "Fix login bug again",
+          url: "https://linear.app/team/issue/ENG-150",
+          description: "Still broken",
+        },
+      },
+    };
+
+    await handleAgentSessionEvent(event);
+
+    // tracker_sync should now point to a NEW task
+    const sync = getTrackerSyncByExternalId("linear", "task", "issue-followup-completed-001");
     expect(sync).not.toBeNull();
+    expect(sync!.swarmId).not.toBe(originalTask.id);
+
+    // New task should exist and use the reassigned template
+    const followupTask = getTaskById(sync!.swarmId);
+    expect(followupTask).not.toBeNull();
+    expect(followupTask!.source).toBe("linear");
+    expect(followupTask!.taskType).toBe("linear-issue");
+    expect(followupTask!.task).toContain("[Linear ENG-150]");
+    expect(followupTask!.task).toContain("Re-assigned");
+  });
+
+  test("creates follow-up task when already-tracked issue has a failed task", async () => {
+    const originalTask = createTaskExtended("Failed linear task", {
+      source: "linear",
+      taskType: "linear-issue",
+    });
+    const { getDb } = await import("../be/db");
+    getDb().query("UPDATE agent_tasks SET status = 'failed' WHERE id = ?").run(originalTask.id);
+
+    createTrackerSync({
+      provider: "linear",
+      entityType: "task",
+      providerEntityType: "Issue",
+      swarmId: originalTask.id,
+      externalId: "issue-followup-failed-001",
+      externalIdentifier: "ENG-151",
+      externalUrl: "https://linear.app/team/issue/ENG-151",
+      lastSyncOrigin: "external",
+      syncDirection: "inbound",
+    });
+
+    const event = {
+      type: "AgentSession",
+      action: "create",
+      data: {
+        issue: {
+          id: "issue-followup-failed-001",
+          identifier: "ENG-151",
+          title: "Deploy pipeline fix",
+          url: "https://linear.app/team/issue/ENG-151",
+        },
+      },
+    };
+
+    await handleAgentSessionEvent(event);
+
+    const sync = getTrackerSyncByExternalId("linear", "task", "issue-followup-failed-001");
+    expect(sync).not.toBeNull();
+    expect(sync!.swarmId).not.toBe(originalTask.id);
+
+    const followupTask = getTaskById(sync!.swarmId);
+    expect(followupTask).not.toBeNull();
+    expect(followupTask!.source).toBe("linear");
   });
 
   test("skips event with no issue data", async () => {