@desplega.ai/agent-swarm 1.51.2 → 1.52.1

package/src/http/skills.ts

@@ -0,0 +1,479 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  createSkill,
+  deleteSkill,
+  getAgentSkills,
+  getSkillById,
+  installSkill,
+  listSkills,
+  searchSkills,
+  uninstallSkill,
+  updateSkill,
+} from "../be/db";
+import { parseSkillContent } from "../be/skill-parser";
+import { syncSkillsToFilesystem } from "../be/skill-sync";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const listSkillsRoute = route({
+  method: "get",
+  path: "/api/skills",
+  pattern: ["api", "skills"],
+  summary: "List skills with optional filters",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  query: z.object({
+    type: z.string().optional(),
+    scope: z.string().optional(),
+    agentId: z.string().optional(),
+    enabled: z.string().optional(),
+    search: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Skill list" },
+  },
+});
+
+const getSkillRoute = route({
+  method: "get",
+  path: "/api/skills/{id}",
+  pattern: ["api", "skills", null],
+  summary: "Get skill by ID",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Skill details" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const createSkillRoute = route({
+  method: "post",
+  path: "/api/skills",
+  pattern: ["api", "skills"],
+  summary: "Create a new skill",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  body: z.object({
+    content: z.string().min(1),
+    type: z.string().optional(),
+    scope: z.string().optional(),
+    ownerAgentId: z.string().optional(),
+  }),
+  responses: {
+    201: { description: "Skill created" },
+    400: { description: "Validation error" },
+  },
+});
+
+const updateSkillRoute = route({
+  method: "put",
+  path: "/api/skills/{id}",
+  pattern: ["api", "skills", null],
+  summary: "Update a skill",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  body: z.record(z.string(), z.unknown()),
+  responses: {
+    200: { description: "Skill updated" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const deleteSkillRoute = route({
+  method: "delete",
+  path: "/api/skills/{id}",
+  pattern: ["api", "skills", null],
+  summary: "Delete a skill",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Skill deleted" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const installSkillRoute = route({
+  method: "post",
+  path: "/api/skills/{id}/install",
+  pattern: ["api", "skills", null, "install"],
+  summary: "Install skill for an agent",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  body: z.object({
+    agentId: z.string(),
+  }),
+  responses: {
+    200: { description: "Skill installed" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const uninstallSkillRoute = route({
+  method: "delete",
+  path: "/api/skills/{id}/install/{agentId}",
+  pattern: ["api", "skills", null, "install", null],
+  summary: "Uninstall skill for an agent",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string(), agentId: z.string() }),
+  responses: {
+    200: { description: "Skill uninstalled" },
+  },
+});
+
+const installRemoteRoute = route({
+  method: "post",
+  path: "/api/skills/install-remote",
+  pattern: ["api", "skills", "install-remote"],
+  summary: "Install a remote skill from GitHub",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  body: z.object({
+    sourceRepo: z.string(),
+    sourcePath: z.string().optional(),
+    scope: z.string().optional(),
+    isComplex: z.boolean().optional(),
+  }),
+  responses: {
+    201: { description: "Remote skill installed" },
+    400: { description: "Fetch failed" },
+  },
+});
+
+const syncRemoteRoute = route({
+  method: "post",
+  path: "/api/skills/sync-remote",
+  pattern: ["api", "skills", "sync-remote"],
+  summary: "Trigger remote skill sync",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  body: z.object({
+    skillId: z.string().optional(),
+    force: z.boolean().optional(),
+  }),
+  responses: {
+    200: { description: "Sync results" },
+  },
+});
+
+const syncFilesystemRoute = route({
+  method: "post",
+  path: "/api/skills/sync-filesystem",
+  pattern: ["api", "skills", "sync-filesystem"],
+  summary: "Sync installed skills to agent filesystem",
+  tags: ["Skills"],
+  auth: { apiKey: true, agentId: true },
+  responses: {
+    200: { description: "Filesystem sync results" },
+  },
+});
+
+const getAgentSkillsRoute = route({
+  method: "get",
+  path: "/api/agents/{id}/skills",
+  pattern: ["api", "agents", null, "skills"],
+  summary: "Get all skills installed for an agent",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Agent skills list" },
+  },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleSkills(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+  myAgentId: string | undefined,
+): Promise<boolean> {
+  // GET /api/agents/:id/skills (must be before /api/skills routes)
+  if (getAgentSkillsRoute.match(req.method, pathSegments)) {
+    const parsed = await getAgentSkillsRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const skills = getAgentSkills(parsed.params.id);
+    json(res, { skills, total: skills.length });
+    return true;
+  }
+
+  // POST /api/skills/install-remote (must be before /api/skills/:id)
+  if (installRemoteRoute.match(req.method, pathSegments)) {
+    const parsed = await installRemoteRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    try {
+      const branch = "main";
+      const filePath = parsed.body.sourcePath ? `${parsed.body.sourcePath}/SKILL.md` : "SKILL.md";
+      const rawUrl = `https://raw.githubusercontent.com/${parsed.body.sourceRepo}/${branch}/${filePath}`;
+
+      let content = "";
+      if (!parsed.body.isComplex) {
+        const response = await fetch(rawUrl);
+        if (!response.ok) {
+          jsonError(res, `Failed to fetch SKILL.md: HTTP ${response.status}`, 400);
+          return true;
+        }
+        content = await response.text();
+      }
+
+      let name: string;
+      let description: string;
+      if (content) {
+        const pm = parseSkillContent(content);
+        name = pm.name;
+        description = pm.description;
+      } else {
+        name = parsed.body.sourcePath?.split("/").pop() || parsed.body.sourceRepo;
+        description = `Complex skill from ${parsed.body.sourceRepo}`;
+      }
+
+      const skill = createSkill({
+        name,
+        description,
+        content,
+        type: "remote",
+        scope: (parsed.body.scope as "global" | "swarm") ?? "global",
+        sourceUrl: rawUrl,
+        sourceRepo: parsed.body.sourceRepo,
+        sourcePath: parsed.body.sourcePath,
+        sourceBranch: branch,
+        isComplex: parsed.body.isComplex ?? false,
+      });
+
+      json(res, { skill }, 201);
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Unknown error", 400);
+    }
+    return true;
+  }
+
+  // POST /api/skills/sync-remote
+  if (syncRemoteRoute.match(req.method, pathSegments)) {
+    const parsed = await syncRemoteRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const remoteSkills = parsed.body.skillId
+      ? (() => {
+          const s = getSkillById(parsed.body.skillId!);
+          return s && s.type === "remote" ? [s] : [];
+        })()
+      : listSkills({ type: "remote" });
+
+    let updated = 0;
+    const errors: string[] = [];
+
+    for (const skill of remoteSkills) {
+      if (skill.isComplex || !skill.sourceRepo) continue;
+      try {
+        const fp = skill.sourcePath ? `${skill.sourcePath}/SKILL.md` : "SKILL.md";
+        const url = `https://raw.githubusercontent.com/${skill.sourceRepo}/${skill.sourceBranch}/${fp}`;
+        const resp = await fetch(url);
+        if (!resp.ok) {
+          errors.push(`${skill.name}: HTTP ${resp.status}`);
+          continue;
+        }
+        const newContent = await resp.text();
+        const newHash = new Bun.CryptoHasher("sha256").update(newContent).digest("hex");
+        const now = new Date().toISOString();
+
+        if (parsed.body.force || newHash !== skill.sourceHash) {
+          const pm = parseSkillContent(newContent);
+          updateSkill(skill.id, {
+            content: newContent,
+            name: pm.name,
+            description: pm.description,
+            allowedTools: pm.allowedTools,
+            model: pm.model,
+            effort: pm.effort,
+            context: pm.context,
+            agent: pm.agent,
+            disableModelInvocation: pm.disableModelInvocation,
+            userInvocable: pm.userInvocable,
+            sourceHash: newHash,
+            lastFetchedAt: now,
+          });
+          updated++;
+        } else {
+          // Content unchanged — still update lastFetchedAt
+          updateSkill(skill.id, { lastFetchedAt: now });
+        }
+      } catch (err) {
+        errors.push(`${skill.name}: ${err instanceof Error ? err.message : "Unknown"}`);
+      }
+    }
+
+    json(res, { updated, checked: remoteSkills.length, errors });
+    return true;
+  }
+
+  // POST /api/skills/sync-filesystem
+  if (syncFilesystemRoute.match(req.method, pathSegments)) {
+    // This endpoint is called by the runner to sync skills to the filesystem
+    const agentId = myAgentId;
+    if (!agentId) {
+      jsonError(res, "X-Agent-ID required", 400);
+      return true;
+    }
+
+    const result = syncSkillsToFilesystem(agentId);
+    json(res, {
+      synced: result.synced,
+      removed: result.removed,
+      errors: result.errors,
+      message: `Synced ${result.synced} skills, removed ${result.removed} stale entries`,
+    });
+    return true;
+  }
+
+  // POST /api/skills/:id/install
+  if (installSkillRoute.match(req.method, pathSegments)) {
+    const parsed = await installSkillRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+
+    try {
+      const agentSkill = installSkill(parsed.body.agentId, parsed.params.id);
+      json(res, { agentSkill });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Install failed", 400);
+    }
+    return true;
+  }
+
+  // DELETE /api/skills/:id/install/:agentId
+  if (uninstallSkillRoute.match(req.method, pathSegments)) {
+    const parsed = await uninstallSkillRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const removed = uninstallSkill(parsed.params.agentId, parsed.params.id);
+    json(res, { success: removed });
+    return true;
+  }
+
+  // GET /api/skills
+  if (listSkillsRoute.match(req.method, pathSegments)) {
+    const parsed = await listSkillsRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skills = parsed.query.search
+      ? searchSkills(parsed.query.search)
+      : listSkills({
+          type: parsed.query.type as "remote" | "personal" | undefined,
+          scope: parsed.query.scope as "global" | "swarm" | "agent" | undefined,
+          ownerAgentId: parsed.query.agentId,
+          isEnabled:
+            parsed.query.enabled !== undefined ? parsed.query.enabled === "true" : undefined,
+        });
+
+    json(res, { skills, total: skills.length });
+    return true;
+  }
+
+  // GET /api/skills/:id
+  if (getSkillRoute.match(req.method, pathSegments)) {
+    const parsed = await getSkillRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    json(res, skill);
+    return true;
+  }
+
+  // POST /api/skills
+  if (createSkillRoute.match(req.method, pathSegments)) {
+    const parsed = await createSkillRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    try {
+      const pm = parseSkillContent(parsed.body.content);
+      const skill = createSkill({
+        name: pm.name,
+        description: pm.description,
+        content: parsed.body.content,
+        type: (parsed.body.type as "remote" | "personal") ?? "personal",
+        scope: (parsed.body.scope as "global" | "swarm" | "agent") ?? "agent",
+        ownerAgentId: parsed.body.ownerAgentId,
+        allowedTools: pm.allowedTools,
+        model: pm.model,
+        effort: pm.effort,
+        context: pm.context,
+        agent: pm.agent,
+        disableModelInvocation: pm.disableModelInvocation,
+        userInvocable: pm.userInvocable,
+      });
+      json(res, { skill }, 201);
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Create failed", 400);
+    }
+    return true;
+  }
+
+  // PUT /api/skills/:id
+  if (updateSkillRoute.match(req.method, pathSegments)) {
+    const parsed = await updateSkillRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const updates: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(parsed.body)) {
+      updates[key] = value;
+    }
+
+    // If content is being updated, re-parse frontmatter
+    if (typeof updates.content === "string") {
+      const pm = parseSkillContent(updates.content as string);
+      updates.name = pm.name;
+      updates.description = pm.description;
+      updates.allowedTools = pm.allowedTools;
+      updates.model = pm.model;
+      updates.effort = pm.effort;
+      updates.context = pm.context;
+      updates.agent = pm.agent;
+      updates.disableModelInvocation = pm.disableModelInvocation;
+      updates.userInvocable = pm.userInvocable;
+    }
+
+    const skill = updateSkill(parsed.params.id, updates as Parameters<typeof updateSkill>[1]);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    json(res, { skill });
+    return true;
+  }
+
+  // DELETE /api/skills/:id
+  if (deleteSkillRoute.match(req.method, pathSegments)) {
+    const parsed = await deleteSkillRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const deleted = deleteSkill(parsed.params.id);
+    if (!deleted) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    json(res, { success: true });
+    return true;
+  }
+
+  return false;
+}

package/src/http/tasks.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { ensure } from "@desplega.ai/business-use";
 import { z } from "zod";
 import {
   cancelTask,
@@ -232,6 +233,24 @@ export async function handleTasks(
         source: (parsed.body.source as import("../types").AgentTaskSource) || "api",
         outputSchema: parsed.body.outputSchema || undefined,
       });
+
+      ensure({
+        id: "created",
+        flow: "task",
+        runId: task.id,
+        data: {
+          taskId: task.id,
+          agentId: task.agentId,
+          source: parsed.body.source || "api",
+          status: task.status,
+          task: task.task.slice(0, 200),
+          priority: task.priority,
+          tags: task.tags,
+          parentTaskId: task.parentTaskId,
+          epicId: task.epicId,
+        },
+      });
+
       json(res, task, 201);
     } catch (error) {
       console.error("[HTTP] Failed to create task:", error);
@@ -291,6 +310,36 @@ export async function handleTasks(
       return true;
     }
 
+    if (task.status === "pending") {
+      ensure({
+        id: "cancelled_pending",
+        flow: "task",
+        runId: parsed.params.id,
+        depIds: ["created"],
+        data: {
+          taskId: parsed.params.id,
+          agentId: task.agentId,
+          previousStatus: task.status,
+          reason,
+        },
+        validator: (data) => data.previousStatus === "pending",
+      });
+    } else {
+      ensure({
+        id: "cancelled_in_progress",
+        flow: "task",
+        runId: parsed.params.id,
+        depIds: ["started"],
+        data: {
+          taskId: parsed.params.id,
+          agentId: task.agentId,
+          previousStatus: task.status,
+          reason,
+        },
+        validator: (data) => data.previousStatus === "in_progress",
+      });
+    }
+
     if (task.agentId) {
       updateAgentStatusFromCapacity(task.agentId);
     }
@@ -386,6 +435,25 @@ export async function handleTasks(
       return true;
     }
 
+    if (result.task && !("alreadyFinished" in result && result.alreadyFinished)) {
+      const finishEventId = parsed.body.status === "completed" ? "completed" : "failed";
+      ensure({
+        id: finishEventId,
+        flow: "task",
+        runId: parsed.params.id,
+        depIds: ["started"],
+        data: {
+          taskId: parsed.params.id,
+          agentId: myAgentId,
+          previousStatus: "in_progress",
+          ...(finishEventId === "completed"
+            ? { hasOutput: !!parsed.body.output }
+            : { failureReason: parsed.body.failureReason }),
+        },
+        validator: (data) => data.previousStatus === "in_progress",
+      });
+    }
+
     json(res, {
       success: true,
       alreadyFinished: "alreadyFinished" in result ? result.alreadyFinished : false,
@@ -430,6 +498,19 @@ export async function handleTasks(
       return true;
     }
 
+    ensure({
+      id: "paused",
+      flow: "task",
+      runId: parsed.params.id,
+      depIds: ["started"],
+      data: {
+        taskId: parsed.params.id,
+        agentId: task.agentId,
+        previousStatus: task.status,
+      },
+      validator: (data) => data.previousStatus === "in_progress",
+    });
+
     json(res, { success: true, task: pausedTask });
     return true;
   }
@@ -460,6 +541,19 @@ export async function handleTasks(
       return true;
     }
 
+    ensure({
+      id: "resumed",
+      flow: "task",
+      runId: parsed.params.id,
+      depIds: ["paused"],
+      data: {
+        taskId: parsed.params.id,
+        agentId: task.agentId,
+        previousStatus: task.status,
+      },
+      validator: (data) => data.previousStatus === "paused",
+    });
+
     json(res, { success: true, task: resumedTask });
     return true;
   }

package/src/linear/outbound.ts

@@ -1,12 +1,7 @@
 import { getTrackerSync, updateTrackerSync } from "../be/db-queries/tracker";
 import { workflowEventBus } from "../workflows/event-bus";
 import { getLinearClient } from "./client";
-import {
-  endAgentSession,
-  postAgentSessionAction,
-  postAgentSessionThought,
-  taskSessionMap,
-} from "./sync";
+import { endAgentSession, postAgentSessionAction, taskSessionMap } from "./sync";
 
 let subscribed = false;
 
@@ -60,8 +55,9 @@ async function handleTaskProgress(data: unknown): Promise<void> {
   const sessionId = taskSessionMap.get(taskId);
   if (!sessionId) return;
 
-  postAgentSessionThought(sessionId, progress).catch((err) => {
-    console.error(`[Linear Outbound] Failed to post progress thought for task ${taskId}:`, err);
+  // Use 'action' activity type — Linear renders it as a structured tool invocation card
+  postAgentSessionAction(sessionId, progress).catch((err) => {
+    console.error(`[Linear Outbound] Failed to post progress action for task ${taskId}:`, err);
   });
 }
 
@@ -75,7 +71,9 @@ async function handleTaskCompleted(data: unknown): Promise<void> {
   if (shouldSkipForLoopPrevention(sync)) return;
 
   const sessionId = taskSessionMap.get(taskId);
-  const body = output ? `Task completed.\n\n${output.slice(0, 2000)}` : "Task completed.";
+  const body = output
+    ? `Task completed.\n\n+++ Output\n${output.slice(0, 2000)}\n+++`
+    : "Task completed.";
 
   // Prefer AgentSession activity (shows in the agent panel) over issue comment (avoids duplication)
   if (sessionId) {
@@ -93,7 +91,7 @@ async function handleTaskCompleted(data: unknown): Promise<void> {
         return;
       }
       const comment = output
-        ? `Task completed by swarm agent.\n\nOutput:\n${output.slice(0, 2000)}`
+        ? `Task completed by swarm agent.\n\n+++ Output\n${output.slice(0, 2000)}\n+++`
         : "Task completed by swarm agent.";
       await client.createComment({ issueId: sync.externalId, body: comment });
       console.log(`[Linear Outbound] Posted completion comment for task ${taskId}`);
@@ -121,7 +119,9 @@ async function handleTaskFailed(data: unknown): Promise<void> {
   if (shouldSkipForLoopPrevention(sync)) return;
 
   const sessionId = taskSessionMap.get(taskId);
-  const body = failureReason ? `Task failed.\n\n${failureReason.slice(0, 2000)}` : "Task failed.";
+  const body = failureReason
+    ? `Task failed.\n\n+++ Error Details\n${failureReason.slice(0, 2000)}\n+++`
+    : "Task failed.";
 
   // Prefer AgentSession error activity over issue comment (avoids duplication)
   if (sessionId) {
@@ -139,7 +139,7 @@ async function handleTaskFailed(data: unknown): Promise<void> {
         return;
       }
       const comment = failureReason
-        ? `Task failed.\n\nReason:\n${failureReason.slice(0, 2000)}`
+        ? `Task failed.\n\n+++ Error Details\n${failureReason.slice(0, 2000)}\n+++`
         : "Task failed.";
       await client.createComment({ issueId: sync.externalId, body: comment });
       console.log(`[Linear Outbound] Posted failure comment for task ${taskId}`);

package/src/prompts/base-prompt.ts

@@ -38,6 +38,8 @@ export type BasePromptArgs = {
     clonePath: string;
     warning?: string | null;
   };
+  /** Pre-fetched skill summaries for the installed skills section */
+  skillsSummary?: { name: string; description: string }[];
 };
 
 export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
@@ -68,6 +70,12 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
     }
   }
 
+  // Installed skills section (progressive disclosure — name + description only)
+  if (args.skillsSummary && args.skillsSummary.length > 0) {
+    const summaries = args.skillsSummary.map((s) => `- /${s.name}: ${s.description}`).join("\n");
+    prompt += `\n\n## Installed Skills\n\nThe following skills are available. Use the Skill tool to invoke them by name.\n\n${summaries}\n`;
+  }
+
   // Repo context (protected, never truncated)
   if (args.repoContext) {
     prompt += "\n\n## Repository Context\n\n";