@desplega.ai/agent-swarm 1.87.0 → 1.88.0

package/src/tests/system-default-skills.test.ts

@@ -0,0 +1,119 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  closeDb,
+  createAgent,
+  createSkill,
+  getAgentSkills,
+  getDb,
+  getSystemDefaultSkills,
+  initDb,
+  toggleAgentSkill,
+} from "../be/db";
+import { runSeeder } from "../be/seed";
+import { loadSeedSkills, skillsSeeder } from "../be/seed-skills";
+
+const TEST_DB_PATH = `./test-system-default-skills-${process.pid}.sqlite`;
+
+async function removeDbFiles(path: string): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(path + suffix).catch(() => {});
+  }
+}
+
+describe("system-default skills", () => {
+  beforeAll(async () => {
+    await removeDbFiles(TEST_DB_PATH);
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await removeDbFiles(TEST_DB_PATH);
+  });
+
+  test("seed catalog includes swarm-scripts and marks built-in defaults", async () => {
+    const skills = loadSeedSkills();
+    const names = skills.map((skill) => skill.name);
+
+    expect(names).toContain("swarm-scripts");
+    expect(skills.find((skill) => skill.name === "swarm-scripts")?.systemDefault).toBe(true);
+    expect(skills.find((skill) => skill.name === "kv-storage")?.systemDefault).toBe(true);
+    expect(skills.find((skill) => skill.name === "pages")?.systemDefault).toBe(true);
+
+    const result = await runSeeder(skillsSeeder, { quiet: true });
+    expect(result.failed).toEqual([]);
+
+    const defaults = getSystemDefaultSkills().map((skill) => skill.name);
+    expect(defaults).toContain("swarm-scripts");
+    expect(defaults).toContain("kv-storage");
+    expect(defaults).toContain("pages");
+  });
+
+  test("existing agents see system-default skills through the self-healing view", () => {
+    const existingAgent = createAgent({
+      name: "Existing Default Skill Worker",
+      description: "Created after seeded defaults",
+      role: "worker",
+      isLead: false,
+      status: "idle",
+      maxTasks: 1,
+      capabilities: [],
+    });
+
+    const manualDefault = createSkill({
+      name: "manual-system-default",
+      description: "Manual default",
+      content: "---\nname: manual-system-default\ndescription: Manual default\n---\nBody.",
+      type: "personal",
+      scope: "swarm",
+      systemDefault: true,
+    });
+
+    const skills = getAgentSkills(existingAgent.id);
+    expect(skills.map((skill) => skill.name)).toContain("manual-system-default");
+    expect(skills.find((skill) => skill.id === manualDefault.id)?.isActive).toBe(true);
+  });
+
+  test("new agents get concrete agent_skills rows for system defaults", () => {
+    const beforeAgent = createAgent({
+      name: "Concrete Install Worker",
+      description: "Created with defaults present",
+      role: "worker",
+      isLead: false,
+      status: "idle",
+      maxTasks: 1,
+      capabilities: [],
+    });
+
+    const row = getDb()
+      .prepare<{ count: number }, [string]>(
+        `SELECT COUNT(*) AS count
+         FROM agent_skills
+         WHERE agentId = ?
+           AND skillId IN (SELECT id FROM skills WHERE systemDefault = 1)`,
+      )
+      .get(beforeAgent.id);
+
+    expect(row?.count ?? 0).toBeGreaterThan(0);
+  });
+
+  test("system-default skills remain visible even if an install row is toggled inactive", () => {
+    const agent = createAgent({
+      name: "Inactive Default Worker",
+      description: "Tests self-healing union",
+      role: "worker",
+      isLead: false,
+      status: "idle",
+      maxTasks: 1,
+      capabilities: [],
+    });
+    const skill = getSystemDefaultSkills().find((entry) => entry.name === "swarm-scripts");
+    expect(skill).toBeDefined();
+
+    toggleAgentSkill(agent.id, skill!.id, false);
+    const skills = getAgentSkills(agent.id);
+
+    expect(skills.find((entry) => entry.id === skill!.id)?.isActive).toBe(true);
+  });
+});

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

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   _getInstallationIdForTests,
+  _isE2bSandbox,
   _resetTelemetryStateForTests,
   _resolveCloudMode,
   initTelemetry,
@@ -302,6 +303,91 @@ describe("initTelemetry", () => {
     });
   });
 
+  describe("_isE2bSandbox detection", () => {
+    afterEach(() => {
+      delete process.env.E2B_SANDBOX_ID;
+    });
+
+    test("returns true when E2B_SANDBOX_ID is set", () => {
+      process.env.E2B_SANDBOX_ID = "sbx_abc123";
+      expect(_isE2bSandbox()).toBe(true);
+    });
+
+    test("returns false when E2B_SANDBOX_ID is unset", () => {
+      delete process.env.E2B_SANDBOX_ID;
+      expect(_isE2bSandbox()).toBe(false);
+    });
+
+    test("returns false when E2B_SANDBOX_ID is empty string", () => {
+      process.env.E2B_SANDBOX_ID = "";
+      expect(_isE2bSandbox()).toBe(false);
+    });
+  });
+
+  describe("track() ships is_e2b in properties", () => {
+    const originalFetch = globalThis.fetch;
+    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;
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+      delete process.env.E2B_SANDBOX_ID;
+    });
+
+    test("properties.is_e2b=true when E2B_SANDBOX_ID is set at init", async () => {
+      process.env.E2B_SANDBOX_ID = "sbx_test123";
+      await initTelemetry(
+        "api-server",
+        async () => "install_e2b_test",
+        async () => {},
+      );
+
+      track({ event: "server.started", properties: { port: 3013 } });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_e2b).toBe(true);
+      expect(properties.port).toBe(3013);
+    });
+
+    test("properties.is_e2b=false when E2B_SANDBOX_ID is unset at init", async () => {
+      delete process.env.E2B_SANDBOX_ID;
+      await initTelemetry(
+        "api-server",
+        async () => "install_no_e2b",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_e2b).toBe(false);
+    });
+
+    test("caller properties cannot override is_e2b", async () => {
+      process.env.E2B_SANDBOX_ID = "sbx_override_test";
+      await initTelemetry(
+        "api-server",
+        async () => "install_e2b_override",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: { is_e2b: false } });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_e2b).toBe(true);
+    });
+  });
+
   describe("track() ships is_cloud in properties", () => {
     const originalFetch = globalThis.fetch;
     let captured: Record<string, unknown> | null = null;

package/src/tools/skills/skill-delete.ts

@@ -3,6 +3,9 @@ import * as z from "zod";
 import { deleteSkill, getAgentById, getSkillById } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 
+const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
+  "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
+
 export const registerSkillDeleteTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "skill-delete",
@@ -51,6 +54,17 @@ export const registerSkillDeleteTool = (server: McpServer) => {
         };
       }
 
+      if (existing.systemDefault) {
+        return {
+          content: [{ type: "text", text: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE,
+          },
+        };
+      }
+
       const deleted = deleteSkill(args.skillId);
       return {
         content: [

package/src/tools/skills/skill-update.ts

@@ -4,6 +4,9 @@ import { getAgentById, getSkillById, updateSkill } from "@/be/db";
 import { parseSkillContent } from "@/be/skill-parser";
 import { createToolRegistrar } from "@/tools/utils";
 
+const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
+  "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
+
 export const registerSkillUpdateTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "skill-update",
@@ -77,6 +80,17 @@ export const registerSkillUpdateTool = (server: McpServer) => {
           };
         }
 
+        if (existing.systemDefault && (args.content !== undefined || args.scope !== undefined)) {
+          return {
+            content: [{ type: "text", text: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE,
+            },
+          };
+        }
+
         const updates: Parameters<typeof updateSkill>[1] = {};
 
         if (args.content !== undefined) {

package/src/tools/store-progress.ts

@@ -16,6 +16,7 @@ import {
 import { getEmbeddingProvider, getMemoryStore } from "@/be/memory";
 import { getRetrievalsForTask } from "@/be/memory/raters/retrieval";
 import { runServerRaters } from "@/be/memory/raters/run-server-raters";
+import { shouldPersistTaskCompletionMemory } from "@/memory/automatic-task-gate";
 import { createWorkerTaskFollowUp } from "@/tasks/worker-follow-up";
 import { createToolRegistrar } from "@/tools/utils";
 import { AgentTaskSchema, AttachmentInputSchema, isTerminalTaskStatus } from "@/types";
@@ -56,6 +57,12 @@ export const registerStoreProgressTool = (server: McpServer) => {
           .describe(
             "Pointer-based artifacts produced by this step — agent-fs path, URL, shared-fs path, or swarm Page. No inline file data; upload to agent-fs first and attach by path. May be sent on any call (progress or completion) and accumulates across calls; duplicates are de-duped by sha256 (when present) or by (kind, pointer, name).",
           ),
+        persistMemory: z
+          .boolean()
+          .optional()
+          .describe(
+            "Opt in to task_completion memory persistence for automatic/recurring tasks. Manual tasks are persisted by default; scheduled, system, heartbeat/boot-triage, monitor, and digest tasks are skipped unless this is true.",
+          ),
         // Phase 11: `costData` removed. The harness adapter is the sole
         // writer of `session_costs` (see POST /api/session-costs in the
         // runner). If a payload still includes the field, Zod's
@@ -75,7 +82,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
       }),
     },
     async (
-      { taskId, progress, status, output, failureReason, attachments },
+      { taskId, progress, status, output, failureReason, attachments, persistMemory },
       requestInfo,
       _meta,
     ) => {
@@ -320,14 +327,19 @@ export const registerStoreProgressTool = (server: McpServer) => {
 
       const result = txn();
 
+      const shouldRunTerminalSideEffects =
+        (status === "completed" || status === "failed") &&
+        result.success &&
+        result.task &&
+        !("wasNoOp" in result && result.wasNoOp);
+
       // Index completed and failed tasks as memory (async, non-blocking).
       // Skip on no-op (idempotent re-call on terminal task) to avoid duplicate
       // memory entries / vector index pollution.
+      // Automatic/recurring tasks are noisy by default; require explicit opt-in.
       if (
-        (status === "completed" || status === "failed") &&
-        result.success &&
-        result.task &&
-        !("wasNoOp" in result && result.wasNoOp)
+        shouldRunTerminalSideEffects &&
+        shouldPersistTaskCompletionMemory(result.task, persistMemory)
       ) {
         (async () => {
           try {
@@ -384,7 +396,9 @@ export const registerStoreProgressTool = (server: McpServer) => {
             // Non-blocking — task completion memory failure should not affect task status
           }
         })();
+      }
 
+      if (shouldRunTerminalSideEffects) {
         // Memory rater v1.5 — fire server-side raters on task completion.
         // Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-2.md §5
         //

package/src/types.ts

@@ -1600,6 +1600,7 @@ export const SkillSchema = z.object({
   userInvocable: z.boolean(),
   version: z.number(),
   isEnabled: z.boolean(),
+  systemDefault: z.boolean(),
   createdAt: z.string(),
   lastUpdatedAt: z.string(),
   lastFetchedAt: z.string().nullable(),

package/templates/skills/artifacts/config.json

@@ -9,5 +9,6 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": ["artifacts", "evidence", "qa"]
 }

package/templates/skills/kv-storage/config.json

@@ -9,5 +9,6 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": ["state", "automation", "idempotency"]
 }

package/templates/skills/pages/config.json

@@ -9,6 +9,7 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": [
     "pages",
     "reporting",

package/templates/skills/scheduled-task-resilience/config.json

@@ -9,5 +9,6 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": ["schedules", "reliability", "polling"]
 }

package/templates/skills/swarm-scripts/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: swarm-scripts
+description: Use swarm scripts for bulk SDK calls, repetitive fan-out, and context-efficient data processing.
+---
+
+# Swarm Scripts
+
+Use swarm scripts when direct tool calls would create repetitive work, flood the context window, or require deterministic data processing across many records. Scripts run out-of-process with a typed Swarm SDK and return only the final result to your context.
+
+## Decision Rubric
+
+| Situation | Use |
+|---|---|
+| 1-10 SDK calls, result fits in context | Direct tool call |
+| 10+ items or bulk fan-out SDK operations | Script |
+| Heavy fetch, parse, transform, or aggregation | Script or context-mode |
+| Single expensive web fetch | `ctx_fetch_and_index` |
+| Multi-agent parallel work | Workflow |
+| Logic needed across sessions or agents | Named script |
+
+## Loading Script Tools
+
+The script tools are deferred. Before authoring or running a script, load the relevant tools with ToolSearch:
+
+```text
+script-query-types
+script-upsert
+script-run
+script-search
+script-delete
+```
+
+Use `script-query-types` before non-trivial work so the script matches the live `swarm-sdk.d.ts` and stdlib signatures.
+
+## Inline Script Pattern
+
+Use `script-run` with inline source for one-off work:
+
+```typescript
+export default async function main(args: { status: string; limit: number }, ctx) {
+  const { swarm, logger } = ctx;
+  const result = await swarm.task_list({ status: args.status, limit: args.limit });
+  logger.info(`Fetched ${result.tasks.length} tasks`);
+  return {
+    total: result.tasks.length,
+    tasks: result.tasks.map((task) => ({
+      id: task.id,
+      status: task.status,
+      title: task.task.slice(0, 120),
+    })),
+  };
+}
+```
+
+Keep logs useful but compact. The value returned from `main` is what comes back to your context.
+
+## Named Script Pattern
+
+Use `script-upsert` when the same logic is likely to be reused by another task or agent. Give the script a searchable name, a concrete description, and an intent that explains when to choose it.
+
+Good named scripts:
+
+- Aggregate failures by agent, schedule, or error family.
+- Fetch and normalize a third-party API response.
+- Fan out over many swarm tasks, memories, repos, or schedules.
+- Convert noisy JSON or HTML into a compact summary.
+
+## SDK And Context Gotchas
+
+- `agentId` is propagated to scripts via the `X-Agent-ID` header, so SDK calls run as the invoking agent.
+- `taskId` is not ambient. If a script needs to call `ctx.swarm.task_storeProgress`, pass `taskId` explicitly in `args`.
+- Scripts invoked from a workflow script node may run with a workflow identity rather than a human or worker agent identity.
+- Return compact structured data. Do not return raw logs, full HTML, huge JSON arrays, or large file contents.
+- For a single large web fetch, prefer context-mode `ctx_fetch_and_index`; for repeated fetch/parse/aggregate work, prefer a script.
+
+## Progress Updates From Scripts
+
+Thread task identity explicitly:
+
+```typescript
+export default async function main(args: { taskId: string; items: string[] }, ctx) {
+  const { swarm } = ctx;
+  await swarm.task_storeProgress({
+    taskId: args.taskId,
+    progress: `Processing ${args.items.length} items with a script`,
+  });
+  return { processed: args.items.length };
+}
+```
+
+Do not assume the runtime can infer the current task.

package/templates/skills/swarm-scripts/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "swarm-scripts",
+  "displayName": "Swarm Scripts",
+  "slug": "swarm-scripts",
+  "title": "Swarm Scripts",
+  "description": "Use swarm scripts for bulk SDK calls, repetitive fan-out, and context-efficient data processing.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["scripts", "automation", "context"]
+}

package/templates/skills/swarm-scripts/content.md

@@ -0,0 +1,86 @@
+# Swarm Scripts
+
+Use swarm scripts when direct tool calls would create repetitive work, flood the context window, or require deterministic data processing across many records. Scripts run out-of-process with a typed Swarm SDK and return only the final result to your context.
+
+## Decision Rubric
+
+| Situation | Use |
+|---|---|
+| 1-10 SDK calls, result fits in context | Direct tool call |
+| 10+ items or bulk fan-out SDK operations | Script |
+| Heavy fetch, parse, transform, or aggregation | Script or context-mode |
+| Single expensive web fetch | `ctx_fetch_and_index` |
+| Multi-agent parallel work | Workflow |
+| Logic needed across sessions or agents | Named script |
+
+## Loading Script Tools
+
+The script tools are deferred. Before authoring or running a script, load the relevant tools with ToolSearch:
+
+```text
+script-query-types
+script-upsert
+script-run
+script-search
+script-delete
+```
+
+Use `script-query-types` before non-trivial work so the script matches the live `swarm-sdk.d.ts` and stdlib signatures.
+
+## Inline Script Pattern
+
+Use `script-run` with inline source for one-off work:
+
+```typescript
+export default async function main(args: { status: string; limit: number }, ctx) {
+  const { swarm, logger } = ctx;
+  const result = await swarm.task_list({ status: args.status, limit: args.limit });
+  logger.info(`Fetched ${result.tasks.length} tasks`);
+  return {
+    total: result.tasks.length,
+    tasks: result.tasks.map((task) => ({
+      id: task.id,
+      status: task.status,
+      title: task.task.slice(0, 120),
+    })),
+  };
+}
+```
+
+Keep logs useful but compact. The value returned from `main` is what comes back to your context.
+
+## Named Script Pattern
+
+Use `script-upsert` when the same logic is likely to be reused by another task or agent. Give the script a searchable name, a concrete description, and an intent that explains when to choose it.
+
+Good named scripts:
+
+- Aggregate failures by agent, schedule, or error family.
+- Fetch and normalize a third-party API response.
+- Fan out over many swarm tasks, memories, repos, or schedules.
+- Convert noisy JSON or HTML into a compact summary.
+
+## SDK And Context Gotchas
+
+- `agentId` is propagated to scripts via the `X-Agent-ID` header, so SDK calls run as the invoking agent.
+- `taskId` is not ambient. If a script needs to call `ctx.swarm.task_storeProgress`, pass `taskId` explicitly in `args`.
+- Scripts invoked from a workflow script node may run with a workflow identity rather than a human or worker agent identity.
+- Return compact structured data. Do not return raw logs, full HTML, huge JSON arrays, or large file contents.
+- For a single large web fetch, prefer context-mode `ctx_fetch_and_index`; for repeated fetch/parse/aggregate work, prefer a script.
+
+## Progress Updates From Scripts
+
+Thread task identity explicitly:
+
+```typescript
+export default async function main(args: { taskId: string; items: string[] }, ctx) {
+  const { swarm } = ctx;
+  await swarm.task_storeProgress({
+    taskId: args.taskId,
+    progress: `Processing ${args.items.length} items with a script`,
+  });
+  return { processed: args.items.length };
+}
+```
+
+Do not assume the runtime can infer the current task.

package/templates/skills/workflow-iterate/config.json

@@ -9,6 +9,7 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": [
     "workflows",
     "authoring",

package/templates/skills/workflow-structured-output/config.json

@@ -9,5 +9,6 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": ["workflows", "json", "validation"]
 }

package/tsconfig.json

@@ -43,6 +43,7 @@
     "logs",
     "plugin",
     "docs-site",
-    "assets/video-source"
+    "assets/video-source",
+    "mockups"
   ]
 }