@desplega.ai/agent-swarm 1.83.0 → 1.83.1

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.83.0",
+    "version": "1.83.1",
     "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": [
@@ -6929,10 +6929,17 @@
                     "type": "string"
                   },
                   "cronExpression": {
-                    "type": "string"
+                    "type": [
+                      "string",
+                      "null"
+                    ]
                   },
                   "intervalMs": {
-                    "type": "integer"
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "exclusiveMinimum": 0
                   },
                   "taskTemplate": {
                     "type": "string"
@@ -7896,6 +7903,35 @@
         }
       }
     },
+    "/api/agents/{id}/skills/signature": {
+      "get": {
+        "summary": "Compute a stable signature over an agent's installed skills",
+        "description": "Returns a sha256 hash over per-row mutation fields of the agent's active+enabled skill set. Workers poll this to detect skill changes cheaply without fetching the full list.",
+        "tags": [
+          "Skills"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Skills signature"
+          }
+        }
+      }
+    },
     "/api/scripts/upsert": {
       "post": {
         "operationId": "scripts_upsert",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.83.0",
+  "version": "1.83.1",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -108,12 +108,12 @@
     "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",
-    "@earendil-works/pi-agent-core": "^0.75.3",
-    "@earendil-works/pi-ai": "^0.75.3",
-    "@earendil-works/pi-coding-agent": "^0.75.3",
+    "@earendil-works/pi-agent-core": "^0.75.5",
+    "@earendil-works/pi-ai": "^0.75.5",
+    "@earendil-works/pi-coding-agent": "^0.75.5",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@openai/codex-sdk": "^0.130.0",
-    "@opencode-ai/sdk": "^1.15.4",
+    "@openai/codex-sdk": "^0.133.0",
+    "@opencode-ai/sdk": "^1.15.10",
     "@openfort/openfort-node": "^0.9.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",

package/src/be/db.ts

@@ -4906,8 +4906,8 @@ export function createScheduledTask(data: CreateScheduledTaskData): ScheduledTas
 export interface UpdateScheduledTaskData {
   name?: string;
   description?: string;
-  cronExpression?: string;
-  intervalMs?: number;
+  cronExpression?: string | null;
+  intervalMs?: number | null;
   taskTemplate?: string;
   taskType?: string;
   tags?: string[];

package/src/be/schedules/validate.ts

@@ -0,0 +1,21 @@
+export type MergedScheduleTiming = { mergedCron: string | null; mergedInterval: number | null };
+export type ScheduleTimingPatch = { cronExpression?: string | null; intervalMs?: number | null };
+
+export function mergeScheduleTiming(
+  existing: { cronExpression: string | null; intervalMs: number | null },
+  patch: ScheduleTimingPatch,
+): MergedScheduleTiming {
+  return {
+    mergedCron: patch.cronExpression !== undefined ? patch.cronExpression : existing.cronExpression,
+    mergedInterval: patch.intervalMs !== undefined ? patch.intervalMs : existing.intervalMs,
+  };
+}
+
+export type RecurringTimingError = { kind: "both-null" } | null;
+
+export function validateRecurringTiming(merged: MergedScheduleTiming): RecurringTimingError {
+  if (merged.mergedCron === null && merged.mergedInterval === null) {
+    return { kind: "both-null" };
+  }
+  return null;
+}

package/src/be/skill-sync.ts

@@ -1,9 +1,9 @@
 /**
  * Filesystem sync for skills.
  *
- * Writes installed skills to ~/.claude/skills/<name>/SKILL.md (and optionally
- * ~/.pi/agent/skills/<name>/SKILL.md) so Claude Code and Pi discover them
- * natively.
+ * Writes installed skills to ~/.claude/skills/<name>/SKILL.md,
+ * ~/.pi/agent/skills/<name>/SKILL.md, and ~/.codex/skills/<name>/SKILL.md
+ * so Claude Code, Pi, and Codex discover them natively.
  *
  * This runs on the API side — workers call it via POST /api/skills/sync-filesystem.
  */
@@ -19,6 +19,16 @@ export interface SkillSyncResult {
   errors: string[];
 }
 
+/**
+ * Marker file written into every swarm-managed skill directory. Cleanup
+ * only ever removes directories that contain this marker, so unrelated
+ * personal skills the user installed via the harness's own tooling (e.g.
+ * `codex skills add ...` writing into `~/.codex/skills/<name>/`) are left
+ * untouched even when the API server shares a HOME with the worker (local
+ * dev). See `~/.codex/skills` blast-radius note in PR #555.
+ */
+const SWARM_MARKER_FILE = ".swarm-managed";
+
 /**
  * Sync agent's installed skills to the filesystem.
  *
@@ -27,7 +37,7 @@ export interface SkillSyncResult {
  */
 export function syncSkillsToFilesystem(
   agentId: string,
-  harnessType: "claude" | "pi" | "both" = "both",
+  harnessType: "claude" | "pi" | "codex" | "all" = "all",
   homeOverride?: string,
 ): SkillSyncResult {
   const skills = getAgentSkills(agentId);
@@ -37,12 +47,15 @@ export function syncSkillsToFilesystem(
 
   // Directories to write to
   const skillDirs: string[] = [];
-  if (harnessType === "claude" || harnessType === "both") {
+  if (harnessType === "claude" || harnessType === "all") {
     skillDirs.push(join(home, ".claude", "skills"));
   }
-  if (harnessType === "pi" || harnessType === "both") {
+  if (harnessType === "pi" || harnessType === "all") {
     skillDirs.push(join(home, ".pi", "agent", "skills"));
   }
+  if (harnessType === "codex" || harnessType === "all") {
+    skillDirs.push(join(home, ".codex", "skills"));
+  }
 
   // Ensure base dirs exist
   for (const dir of skillDirs) {
@@ -66,10 +79,12 @@ export function syncSkillsToFilesystem(
     for (const baseDir of skillDirs) {
       const skillDir = join(baseDir, safeName);
       const skillFile = join(skillDir, "SKILL.md");
+      const markerFile = join(skillDir, SWARM_MARKER_FILE);
 
       try {
         mkdirSync(skillDir, { recursive: true });
         writeFileSync(skillFile, skill.content, "utf-8");
+        writeFileSync(markerFile, "", "utf-8");
         synced++;
       } catch (err) {
         errors.push(
@@ -79,7 +94,10 @@ export function syncSkillsToFilesystem(
     }
   }
 
-  // Cleanup: remove skill directories that are no longer installed
+  // Cleanup: only remove directories WE previously created (marker file
+  // present). Leaves user-installed personal skills alone — important on
+  // local dev where ~/.codex/skills holds skills the user installed
+  // outside the swarm.
   let removed = 0;
   for (const baseDir of skillDirs) {
     if (!existsSync(baseDir)) continue;
@@ -87,14 +105,15 @@ export function syncSkillsToFilesystem(
     try {
       const existing = readdirSync(baseDir, { withFileTypes: true });
       for (const entry of existing) {
-        if (entry.isDirectory() && !writtenNames.has(entry.name)) {
-          const skillDir = join(baseDir, entry.name);
-          try {
-            rmSync(skillDir, { recursive: true, force: true });
-            removed++;
-          } catch {
-            // Non-fatal — skip cleanup errors
-          }
+        if (!entry.isDirectory()) continue;
+        if (writtenNames.has(entry.name)) continue;
+        const skillDir = join(baseDir, entry.name);
+        if (!existsSync(join(skillDir, SWARM_MARKER_FILE))) continue;
+        try {
+          rmSync(skillDir, { recursive: true, force: true });
+          removed++;
+        } catch {
+          // Non-fatal — skip cleanup errors
         }
       }
     } catch {
@@ -104,3 +123,34 @@ export function syncSkillsToFilesystem(
 
   return { synced, removed, errors };
 }
+
+export interface SkillsSignature {
+  hash: string;
+  count: number;
+}
+
+/**
+ * Compute a stable signature over an agent's installed-and-enabled skill set.
+ *
+ * Hash inputs are the per-row mutation-tracking fields — any install,
+ * uninstall, toggle, or skill-update mutates at least one of them. Output is
+ * deterministic and contains no timestamps beyond per-row mutation fields.
+ */
+export function computeAgentSkillsSignature(agentId: string): SkillsSignature {
+  const skills = getAgentSkills(agentId);
+  const sorted = [...skills].sort((a, b) => a.id.localeCompare(b.id));
+  const canonical = JSON.stringify(
+    sorted.map((s) => [
+      s.id,
+      s.name,
+      s.version,
+      s.isEnabled,
+      s.isActive,
+      s.lastUpdatedAt,
+      s.sourceHash ?? "",
+      s.installedAt,
+    ]),
+  );
+  const hash = new Bun.CryptoHasher("sha256").update(canonical).digest("hex");
+  return { hash, count: sorted.length };
+}

package/src/commands/runner.ts

@@ -42,6 +42,7 @@ import { parseRateLimitResetTime } from "../utils/error-tracker.ts";
 import { resolveHarnessProvider } from "../utils/harness-provider.ts";
 import { prettyPrintLine, prettyPrintStderr } from "../utils/pretty-print.ts";
 import { scrubSecrets } from "../utils/secret-scrubber.ts";
+import { refreshSkillsIfChanged } from "../utils/skills-refresh.ts";
 import { detectVcsProvider } from "../vcs/index.ts";
 import { interpolate } from "../workflows/template.ts";
 import { awaitCredentials, BootMaxWaitExceededError, EX_CONFIG } from "./credential-wait.ts";
@@ -3511,34 +3512,6 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         }
       }
 
-      // Fetch installed skills for system prompt
-      try {
-        const skillsResp = await fetch(`${apiUrl}/api/agents/${agentId}/skills`, {
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "X-Agent-ID": agentId,
-          },
-        });
-        if (skillsResp.ok) {
-          const skillsData = (await skillsResp.json()) as {
-            skills: {
-              name: string;
-              description: string;
-              isActive: boolean;
-              isEnabled: boolean;
-            }[];
-          };
-          agentSkillsSummary = skillsData.skills
-            .filter((s) => s.isActive && s.isEnabled)
-            .map((s) => ({ name: s.name, description: s.description }));
-          if (agentSkillsSummary.length > 0) {
-            console.log(`[${role}] Loaded ${agentSkillsSummary.length} skills for system prompt`);
-          }
-        }
-      } catch {
-        // Non-fatal — skills are optional
-      }
-
       // Fetch installed MCP servers for system prompt
       try {
         const mcpServersResp = await fetch(`${apiUrl}/api/agents/${agentId}/mcp-servers`, {
@@ -3649,35 +3622,32 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     }
   }
 
-  // ========== Sync skills to filesystem ==========
-  try {
+  // ========== Boot-time skill load (signature-gated, replaces the standalone
+  // skill-fetch + FS sync blocks). The polling loop below calls the same
+  // helper per task to hot-reload skills mid-flight. Skipped for
+  // `claude-managed` (cloud sandbox owns skill delivery).
+  const lastSkillHash: { current: string | null } = { current: null };
+  if (state.harnessProvider !== "claude-managed") {
     console.log(`[${role}] Syncing skills to filesystem...`);
-    const syncHeaders: Record<string, string> = {
-      "Content-Type": "application/json",
-      "X-Agent-ID": agentId,
-    };
-    if (apiKey) syncHeaders.Authorization = `Bearer ${apiKey}`;
-    const syncRes = await fetch(`${swarmUrl}/api/skills/sync-filesystem`, {
-      method: "POST",
-      headers: syncHeaders,
-    });
-    if (syncRes.ok) {
-      const syncResult = (await syncRes.json()) as {
-        synced: number;
-        removed: number;
-        errors: string[];
-      };
-      console.log(
-        `[${role}] Skills synced: ${syncResult.synced} written, ${syncResult.removed} removed`,
-      );
-      if (syncResult.errors.length > 0) {
-        console.warn(`[${role}] Skill sync errors: ${syncResult.errors.join(", ")}`);
+    const skillResult = await refreshSkillsIfChanged(
+      { apiUrl, swarmUrl, apiKey, agentId, role },
+      lastSkillHash,
+    );
+    if (skillResult.changed && skillResult.summary) {
+      agentSkillsSummary = skillResult.summary;
+      if (agentSkillsSummary.length > 0) {
+        console.log(`[${role}] Loaded ${agentSkillsSummary.length} skills for system prompt`);
       }
-    } else {
-      console.warn(`[${role}] Skill sync failed: HTTP ${syncRes.status}`);
+      // Rebuild base prompt now that we have skills.
+      basePrompt = await buildSystemPrompt();
+      resolvedSystemPrompt = additionalSystemPrompt
+        ? `${basePrompt}\n\n${additionalSystemPrompt}`
+        : basePrompt;
     }
-  } catch (err) {
-    console.warn(`[${role}] Skill sync failed: ${(err as Error).message}`);
+  } else {
+    console.log(
+      `[${role}] Skipping skill sync (claude-managed reads skills from agent definition)`,
+    );
   }
 
   // ========== Resume paused tasks with PRIORITY ==========
@@ -4168,6 +4138,23 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           cwdWarning = `\n\nNote: The task requested working directory "${taskDir}" but it does not exist. Falling back to default directory.`;
         }
 
+        // Per-task skill hot-reload. Reuses the boot-time helper; signature
+        // probe short-circuits when nothing changed. Skipped for
+        // `claude-managed`. Read state.harnessProvider live so an adapter
+        // swap mid-loop honors the new provider.
+        if (state.harnessProvider !== "claude-managed") {
+          const skillResult = await refreshSkillsIfChanged(
+            { apiUrl, swarmUrl, apiKey, agentId, role },
+            lastSkillHash,
+          );
+          if (skillResult.changed && skillResult.summary) {
+            agentSkillsSummary = skillResult.summary;
+            console.log(
+              `[${role}] Skills changed — refreshing system prompt (${agentSkillsSummary.length} skills)`,
+            );
+          }
+        }
+
         // Rebuild system prompt with per-task repo context
         const taskBasePrompt = await buildSystemPrompt();
         const taskSystemPrompt =

package/src/http/schedules.ts

@@ -11,6 +11,7 @@ import {
   getScheduledTasks,
   updateScheduledTask,
 } from "../be/db";
+import { mergeScheduleTiming, validateRecurringTiming } from "../be/schedules/validate";
 import { calculateNextRun } from "../scheduler/scheduler";
 import { scheduleContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
@@ -115,8 +116,8 @@ const updateSchedule = route({
   body: z.object({
     name: z.string().optional(),
     description: z.string().optional(),
-    cronExpression: z.string().optional(),
-    intervalMs: z.number().int().optional(),
+    cronExpression: z.string().nullable().optional(),
+    intervalMs: z.number().int().positive().nullable().optional(),
     taskTemplate: z.string().optional(),
     taskType: z.string().optional(),
     tags: z.array(z.string()).optional(),
@@ -400,6 +401,22 @@ export async function handleSchedules(
       return true;
     }
 
+    // Validate merged timing state — catches cases where one side is null in the DB
+    // and the patch nulls the other, which the schema-level check cannot see.
+    if (existing.scheduleType !== "one_time") {
+      const timing = mergeScheduleTiming(
+        {
+          cronExpression: existing.cronExpression ?? null,
+          intervalMs: existing.intervalMs ?? null,
+        },
+        { cronExpression: parsed.body.cronExpression, intervalMs: parsed.body.intervalMs },
+      );
+      if (validateRecurringTiming(timing)) {
+        jsonError(res, "At least one of intervalMs or cronExpression must be set", 400);
+        return true;
+      }
+    }
+
     if (parsed.body.cronExpression) {
       try {
         CronExpressionParser.parse(parsed.body.cronExpression);
@@ -439,14 +456,22 @@ export async function handleSchedules(
         parsed.body.intervalMs !== undefined ||
         (parsed.body.enabled === true && !existing.enabled)
       ) {
-        const merged = {
-          cronExpression: parsed.body.cronExpression ?? existing.cronExpression,
-          intervalMs: parsed.body.intervalMs ?? existing.intervalMs,
-          timezone: parsed.body.timezone ?? existing.timezone,
-        };
-        if (merged.cronExpression || merged.intervalMs) {
+        const timing = mergeScheduleTiming(
+          {
+            cronExpression: existing.cronExpression ?? null,
+            intervalMs: existing.intervalMs ?? null,
+          },
+          { cronExpression: parsed.body.cronExpression, intervalMs: parsed.body.intervalMs },
+        );
+        const mergedTimezone =
+          parsed.body.timezone !== undefined ? parsed.body.timezone : existing.timezone;
+        if (timing.mergedCron || timing.mergedInterval) {
           // biome-ignore lint/suspicious/noExplicitAny: need partial ScheduledTask for calculateNextRun
-          body.nextRunAt = calculateNextRun(merged as any);
+          body.nextRunAt = calculateNextRun({
+            cronExpression: timing.mergedCron,
+            intervalMs: timing.mergedInterval,
+            timezone: mergedTimezone,
+          } as any);
         }
       }
     }

package/src/http/skills.ts

@@ -12,7 +12,7 @@ import {
   updateSkill,
 } from "../be/db";
 import { parseSkillContent } from "../be/skill-parser";
-import { syncSkillsToFilesystem } from "../be/skill-sync";
+import { computeAgentSkillsSignature, syncSkillsToFilesystem } from "../be/skill-sync";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -193,6 +193,21 @@ const getAgentSkillsRoute = route({
   },
 });
 
+const getAgentSkillsSignatureRoute = route({
+  method: "get",
+  path: "/api/agents/{id}/skills/signature",
+  pattern: ["api", "agents", null, "skills", "signature"],
+  summary: "Compute a stable signature over an agent's installed skills",
+  description:
+    "Returns a sha256 hash over per-row mutation fields of the agent's active+enabled skill set. Workers poll this to detect skill changes cheaply without fetching the full list.",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Skills signature" },
+  },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleSkills(
@@ -202,12 +217,22 @@ export async function handleSkills(
   queryParams: URLSearchParams,
   myAgentId: string | undefined,
 ): Promise<boolean> {
+  // GET /api/agents/:id/skills/signature (must come before the shorter pattern)
+  if (getAgentSkillsSignatureRoute.match(req.method, pathSegments)) {
+    const parsed = await getAgentSkillsSignatureRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const sig = computeAgentSkillsSignature(parsed.params.id);
+    json(res, { hash: sig.hash, count: sig.count, generatedAt: new Date().toISOString() });
+    return true;
+  }
+
   // 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 });
+    const signature = computeAgentSkillsSignature(parsed.params.id).hash;
+    json(res, { skills, total: skills.length, signature });
     return true;
   }
 

package/src/tests/http-api-integration.test.ts

@@ -968,6 +968,42 @@ describe("Schedule CRUD", () => {
     expect(status).toBe(404);
   });
 
+  test("PUT /api/schedules/:id — cron-based schedule accepts null intervalMs", async () => {
+    // Reproduces CAI-1283: dashboard sends null for unused timing field
+    const { status, body } = await put(`/api/schedules/${scheduleId}`, {
+      body: { cronExpression: "0 2 * * *", intervalMs: null },
+    });
+    expect(status).toBe(200);
+    expect(body.cronExpression).toBe("0 2 * * *");
+    // intervalMs omitted from response when not set (null serialized as undefined in JSON)
+    expect(body.intervalMs == null).toBe(true);
+  });
+
+  test("PUT /api/schedules/:id — interval-based schedule accepts null cronExpression", async () => {
+    // Create an interval-based schedule to test against
+    const { body: created } = await post("/api/schedules", {
+      body: {
+        name: "interval-test-cai-1283",
+        taskTemplate: "interval task",
+        intervalMs: 60000,
+      },
+    });
+    const { status, body } = await put(`/api/schedules/${created.id}`, {
+      body: { intervalMs: 60000, cronExpression: null },
+    });
+    expect(status).toBe(200);
+    expect(body.intervalMs).toBe(60000);
+    // Clean up
+    await del(`/api/schedules/${created.id}`);
+  });
+
+  test("PUT /api/schedules/:id — both intervalMs and cronExpression null returns 400", async () => {
+    const { status } = await put(`/api/schedules/${scheduleId}`, {
+      body: { cronExpression: null, intervalMs: null },
+    });
+    expect(status).toBe(400);
+  });
+
   test("POST /api/schedules/:id/run — run now creates a task", async () => {
     const { status, body } = await post(`/api/schedules/${scheduleId}/run`);
     expect(status).toBe(200);