@desplega.ai/agent-swarm 1.78.0 → 1.79.0

package/src/tests/skill-update-scope.test.ts

@@ -0,0 +1,165 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, createAgent, createSkill, getSkillById, initDb } from "../be/db";
+import { registerSkillUpdateTool } from "../tools/skills/skill-update";
+
+const TEST_DB_PATH = "./test-skill-update-scope.sqlite";
+
+const LEAD_ID = "aaaa0000-0000-4000-8000-000000000010";
+const WORKER_ID = "bbbb0000-0000-4000-8000-000000000020";
+
+type StructuredContent = {
+  yourAgentId?: string;
+  success: boolean;
+  message: string;
+  skill?: { id: string; scope: string; ownerAgentId: string | null };
+};
+
+async function callSkillUpdate(
+  server: McpServer,
+  callerAgentId: string | undefined,
+  args: Record<string, unknown>,
+): Promise<{ structuredContent: StructuredContent }> {
+  // biome-ignore lint/complexity/noBannedTypes: accessing internal MCP SDK type for test
+  const tools = (server as unknown as { _registeredTools: Record<string, { handler: Function }> })
+    ._registeredTools;
+  const handler = tools["skill-update"].handler;
+
+  const extra = {
+    sessionId: "test-session",
+    requestInfo: {
+      headers: {
+        "x-agent-id": callerAgentId ?? "",
+      },
+    },
+  };
+
+  const result = await handler(args, extra);
+  return result as { structuredContent: StructuredContent };
+}
+
+describe("skill-update scope promotion", () => {
+  let server: McpServer;
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {
+        // File doesn't exist
+      }
+    }
+
+    closeDb();
+    initDb(TEST_DB_PATH);
+
+    createAgent({ id: LEAD_ID, name: "Test Lead", isLead: true, status: "idle" });
+    createAgent({ id: WORKER_ID, name: "Test Worker", isLead: false, status: "idle" });
+
+    server = new McpServer({ name: "test-skill-update-scope", version: "1.0.0" });
+    registerSkillUpdateTool(server);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  test("worker cannot promote their own skill to swarm scope", async () => {
+    const skill = createSkill({
+      name: "worker-skill-self-promote",
+      description: "Worker tries to promote",
+      content:
+        "---\nname: worker-skill-self-promote\ndescription: Worker tries to promote\n---\n\nBody.",
+      type: "personal",
+      scope: "agent",
+      ownerAgentId: WORKER_ID,
+    });
+
+    const result = await callSkillUpdate(server, WORKER_ID, {
+      skillId: skill.id,
+      scope: "swarm",
+    });
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("lead");
+
+    const stored = getSkillById(skill.id);
+    expect(stored?.scope).toBe("agent");
+    expect(stored?.ownerAgentId).toBe(WORKER_ID);
+  });
+
+  test("lead can promote a worker's agent-scope skill to swarm without changing ownerAgentId", async () => {
+    const skill = createSkill({
+      name: "worker-skill-lead-promote",
+      description: "Lead promotes",
+      content: "---\nname: worker-skill-lead-promote\ndescription: Lead promotes\n---\n\nBody.",
+      type: "personal",
+      scope: "agent",
+      ownerAgentId: WORKER_ID,
+    });
+
+    const result = await callSkillUpdate(server, LEAD_ID, {
+      skillId: skill.id,
+      scope: "swarm",
+    });
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.skill?.scope).toBe("swarm");
+    expect(result.structuredContent.skill?.ownerAgentId).toBe(WORKER_ID);
+
+    const stored = getSkillById(skill.id);
+    expect(stored?.scope).toBe("swarm");
+    expect(stored?.ownerAgentId).toBe(WORKER_ID);
+  });
+
+  test("lead demoting a swarm skill back to agent scope is allowed", async () => {
+    const skill = createSkill({
+      name: "swarm-skill-demote",
+      description: "Demote test",
+      content: "---\nname: swarm-skill-demote\ndescription: Demote test\n---\n\nBody.",
+      type: "personal",
+      scope: "swarm",
+      ownerAgentId: WORKER_ID,
+    });
+
+    const result = await callSkillUpdate(server, LEAD_ID, {
+      skillId: skill.id,
+      scope: "agent",
+    });
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.skill?.scope).toBe("agent");
+
+    const stored = getSkillById(skill.id);
+    expect(stored?.scope).toBe("agent");
+  });
+
+  test("omitting scope leaves it unchanged", async () => {
+    const skill = createSkill({
+      name: "scope-untouched",
+      description: "No scope change",
+      content: "---\nname: scope-untouched\ndescription: No scope change\n---\n\nBody.",
+      type: "personal",
+      scope: "agent",
+      ownerAgentId: WORKER_ID,
+    });
+
+    const result = await callSkillUpdate(server, WORKER_ID, {
+      skillId: skill.id,
+      isEnabled: false,
+    });
+
+    expect(result.structuredContent.success).toBe(true);
+    const stored = getSkillById(skill.id);
+    expect(stored?.scope).toBe("agent");
+    expect(stored?.isEnabled).toBe(false);
+  });
+});

package/src/tests/workflow-wait-event.test.ts

@@ -261,13 +261,10 @@ describe("WaitExecutor — event mode end-to-end", () => {
 
     // Skip the 5s poller — fast-forward by directly calling the resume helper
     // with status='timeout' (the poller would do exactly this once expiresAt
-    // passes). Sleep relative to the *actual* expiresAt so we don't race
-    // when startWorkflowExecution overhead eats the cushion on slow CI.
-    const expiresAtMs = new Date(ws!.expiresAt!).getTime();
-    const sleepMs = Math.max(0, expiresAtMs - Date.now()) + 250;
-    await new Promise((r) => setTimeout(r, sleepMs));
-    const due = getDueWaitStates();
-    expect(due.find((d) => d.id === ws!.id)).toBeDefined();
+    // passes). Poll getDueWaitStates() instead of sleeping a fixed amount:
+    // SQLite's strftime('now') and JS Date.now() can drift by a few ms on
+    // loaded CI, and setTimeout cushions need to be generous to compensate.
+    await waitFor(() => getDueWaitStates().some((d) => d.id === ws!.id), 5000);
 
     await resumeWaitState(ws!.id, "timeout", undefined, registry);
 

package/src/tools/create-page.ts

@@ -0,0 +1,263 @@
+/**
+ * `create_page` MCP tool — capability-gated ("pages") agent-facing entry
+ * point for the db-backed pages feature. Creates or updates a page row in
+ * SQLite and returns shareable URLs.
+ *
+ * Upsert semantics: keyed by `(agentId, slug)`. If a row already exists,
+ * the tool calls `snapshotPage` (preserving pre-update content as a version
+ * row) then `updatePage` — mirroring the HTTP `PUT /api/pages/:id` flow.
+ * First-create skips the snapshot (no prior state).
+ *
+ * Slug derivation: explicit `slug` wins; otherwise kebab-case the title; if
+ * the title slugifies to empty (e.g. all symbols), fall back to the
+ * generated page id.
+ *
+ * Architecture note: this tool runs on the API server (per
+ * `src/server.ts:155`+ pattern) and accesses `src/be/db` directly. The
+ * worker-side DB-boundary invariant doesn't apply because `src/tools/*`
+ * lives on the API side.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createPage, getPage, getPageBySlug, getPageVersions, updatePage } from "@/be/db";
+import { snapshotPage } from "@/pages/version";
+import { createToolRegistrar } from "@/tools/utils";
+import { PageAuthModeSchema, PageContentTypeSchema } from "@/types";
+
+/** Same slugifier used by the HTTP createPage handler. */
+function slugify(input: string): string {
+  const slug = input
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug;
+}
+
+function getApiBaseUrl(): string {
+  const env = process.env.MCP_BASE_URL?.trim();
+  if (env) return env.replace(/\/+$/, "");
+  return `http://localhost:${process.env.PORT || "3013"}`;
+}
+
+function getAppBaseUrl(): string {
+  const env = process.env.APP_URL?.trim();
+  if (env) return env.replace(/\/+$/, "");
+  return "http://localhost:5274";
+}
+
+/**
+ * Edit counter for a page — `MAX(page_versions.version) + 1`. Returned to
+ * the agent as `version` so they have a monotonic "this page has been
+ * edited N times" signal. Mirrors the value returned by
+ * `PUT /api/pages/:id` (see src/http/pages.ts:pageEditCounter).
+ */
+function pageEditCounter(pageId: string): number {
+  const versions = getPageVersions(pageId);
+  return versions.length > 0 ? versions[0]!.version + 1 : 1;
+}
+
+export const registerCreatePageTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "create_page",
+    {
+      title: "Create or update a page",
+      description:
+        "Stores an HTML or JSON page in the swarm and returns shareable URLs. " +
+        "Calls are upsert-by-(agent, slug): if you previously created a page " +
+        "with the same slug, its prior state is snapshotted and the row is " +
+        "updated. Use this for static reports, dashboards, or JSON action " +
+        "specs that don't need a long-lived process.",
+      annotations: { destructiveHint: false },
+      inputSchema: z.object({
+        title: z.string().min(1).describe("Human-readable title shown in listings."),
+        slug: z
+          .string()
+          .min(1)
+          .optional()
+          .describe(
+            "URL slug. Defaults to the kebab-cased title. Same slug → updates the existing row.",
+          ),
+        body: z
+          .string()
+          .min(1)
+          .describe("Full page body (HTML document or JSON-render spec, per contentType)."),
+        contentType: PageContentTypeSchema.describe(
+          "'text/html' renders directly at /p/:id; 'application/json' is rendered by the SPA.",
+        ),
+        authMode: PageAuthModeSchema.default("public").describe(
+          "'public' — no gate; 'authed' — requires page-session cookie; 'password' — requires key.",
+        ),
+        password: z
+          .string()
+          .min(1)
+          .optional()
+          .describe(
+            "Plaintext password, hashed before storage. Only meaningful for authMode='password'.",
+          ),
+        description: z
+          .string()
+          .optional()
+          .describe("Optional short description, used in listings + OG-tag unfurl."),
+        needsCredentials: z
+          .array(z.object({ name: z.string(), description: z.string() }))
+          .optional()
+          .describe(
+            "Declared credential needs for JSON pages (renderer ignores for v1 — reserved for follow-up).",
+          ),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string(),
+        id: z.string(),
+        version: z.number(),
+        app_url: z.string(),
+        api_url: z.string(),
+      }),
+    },
+    async (input, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        const msg = "Agent ID required. Set the X-Agent-ID header on the MCP request.";
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: "",
+            id: "",
+            version: 0,
+            app_url: "",
+            api_url: "",
+            success: false,
+            message: msg,
+          },
+          isError: true,
+        };
+      }
+
+      const slug = input.slug ?? slugify(input.title);
+      const finalSlug = slug || "page"; // Fallback if title slugifies to empty.
+
+      // Hash password if provided. We always hash (even for non-password
+      // modes) so the column reflects what the caller intended; the mode
+      // governs whether the hash is checked at /p/:id serve time.
+      let passwordHash: string | undefined;
+      if (input.password) {
+        passwordHash = await Bun.password.hash(input.password, "bcrypt");
+      }
+
+      // `needsCredentials` is declared as `[{name, description}]` on the
+      // wire but the DB column accepts string[] (current schema). Flatten
+      // to names for v1 — the renderer ignores it anyway. Step-8 may
+      // revisit.
+      const needsCredentialsNames = input.needsCredentials?.map((c) => c.name);
+
+      // Upsert. Look up existing row by (agentId, slug).
+      const existing = getPageBySlug(requestInfo.agentId, finalSlug);
+
+      let id: string;
+      if (existing) {
+        // Snapshot first — failure must NOT block the update.
+        try {
+          snapshotPage(existing.id, requestInfo.agentId);
+        } catch {
+          // intentional empty
+        }
+        const updated = updatePage(existing.id, {
+          title: input.title,
+          description: input.description,
+          contentType: input.contentType,
+          authMode: input.authMode,
+          passwordHash: passwordHash ?? null,
+          body: input.body,
+          needsCredentials: needsCredentialsNames ?? null,
+        });
+        if (!updated) {
+          const msg = `Failed to update existing page ${existing.id}.`;
+          return {
+            content: [{ type: "text", text: msg }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              id: existing.id,
+              version: 0,
+              app_url: "",
+              api_url: "",
+              success: false,
+              message: msg,
+            },
+            isError: true,
+          };
+        }
+        id = updated.id;
+      } else {
+        try {
+          const created = createPage({
+            agentId: requestInfo.agentId,
+            slug: finalSlug,
+            title: input.title,
+            description: input.description,
+            contentType: input.contentType,
+            authMode: input.authMode,
+            passwordHash,
+            body: input.body,
+            needsCredentials: needsCredentialsNames,
+          });
+          id = created.id;
+        } catch (err) {
+          const detail = err instanceof Error ? err.message : String(err);
+          const msg = `Failed to create page: ${detail}`;
+          return {
+            content: [{ type: "text", text: msg }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              id: "",
+              version: 0,
+              app_url: "",
+              api_url: "",
+              success: false,
+              message: msg,
+            },
+            isError: true,
+          };
+        }
+      }
+
+      // Re-read after write so the page exists (defensive). 1 round-trip;
+      // page row is small. If it's missing here something's badly wrong.
+      const fresh = getPage(id);
+      if (!fresh) {
+        const msg = `Page ${id} disappeared between write and read.`;
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            id,
+            version: 0,
+            app_url: "",
+            api_url: "",
+            success: false,
+            message: msg,
+          },
+          isError: true,
+        };
+      }
+
+      const apiUrl = `${getApiBaseUrl()}/p/${id}`;
+      const appUrl = `${getAppBaseUrl()}/pages/${id}`;
+      const version = pageEditCounter(id);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Page "${input.title}" saved (slug=${finalSlug}, version=${version}).\n  API: ${apiUrl}\n  App: ${appUrl}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          id,
+          version,
+          app_url: appUrl,
+          api_url: apiUrl,
+        },
+      };
+    },
+  );
+};

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

@@ -16,6 +16,12 @@ export const registerSkillUpdateTool = (server: McpServer) => {
         skillId: z.string().optional().describe("Skill ID to update"),
         content: z.string().optional().describe("New SKILL.md content (re-parses frontmatter)"),
         isEnabled: z.boolean().optional().describe("Toggle enabled/disabled"),
+        scope: z
+          .enum(["agent", "swarm"])
+          .optional()
+          .describe(
+            "Scope: agent (personal) or swarm (shared). Only leads can promote a skill to swarm scope (used by the skill-approval flow).",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -91,6 +97,26 @@ export const registerSkillUpdateTool = (server: McpServer) => {
           updates.isEnabled = args.isEnabled;
         }
 
+        if (args.scope !== undefined && args.scope !== existing.scope) {
+          // Promoting to swarm scope is the skill-approval path — only leads may do it.
+          if (args.scope === "swarm" && !agent?.isLead) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: 'Only lead agents can promote a skill to "swarm" scope. Use "skill-publish" to request approval.',
+                },
+              ],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: "Only lead agents can promote a skill to swarm scope.",
+              },
+            };
+          }
+          updates.scope = args.scope;
+        }
+
         const skill = updateSkill(args.skillId, updates);
         if (!skill) {
           return {

package/src/tools/tool-config.ts

@@ -144,6 +144,9 @@ export const DEFERRED_TOOLS = new Set([
   "resolve-user",
   "manage-user",
 
+  // Pages (1)
+  "create_page",
+
   // Other (3)
   "cancel-task",
   "inject-learning",

package/src/types.ts

@@ -1087,6 +1087,60 @@ export const WorkflowVersionSchema = z.object({
 });
 export type WorkflowVersion = z.infer<typeof WorkflowVersionSchema>;
 
+// ---------------------------------------------------------------------------
+// Pages — DB-backed lightweight artifacts (HTML or JSON spec) stored in
+// SQLite and served at /p/:id. See plan: thoughts/taras/plans/2026-05-12-db-backed-pages/.
+// PageContentTypeSchema + PageAuthModeSchema MUST stay in sync with the SQL
+// CHECK constraints in src/be/migrations/059_pages.sql.
+// ---------------------------------------------------------------------------
+
+export const PageContentTypeSchema = z.enum(["text/html", "application/json"]);
+export type PageContentType = z.infer<typeof PageContentTypeSchema>;
+
+export const PageAuthModeSchema = z.enum(["public", "authed", "password"]);
+export type PageAuthMode = z.infer<typeof PageAuthModeSchema>;
+
+// PageSnapshot captures the mutable content fields frozen per-version in
+// page_versions.snapshot. Omits id / agentId / slug / timestamps (these are
+// invariant across versions for a given page id; the slug is a parent-only
+// identifier).
+export const PageSnapshotSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  contentType: PageContentTypeSchema,
+  authMode: PageAuthModeSchema,
+  passwordHash: z.string().optional(),
+  body: z.string(),
+  needsCredentials: z.array(z.string()).optional(),
+});
+export type PageSnapshot = z.infer<typeof PageSnapshotSchema>;
+
+export const PageSchema = z.object({
+  id: z.string(),
+  agentId: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  contentType: PageContentTypeSchema,
+  authMode: PageAuthModeSchema,
+  passwordHash: z.string().optional(),
+  body: z.string(),
+  needsCredentials: z.array(z.string()).optional(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Page = z.infer<typeof PageSchema>;
+
+export const PageVersionSchema = z.object({
+  id: z.string(),
+  pageId: z.string(),
+  version: z.number().int().min(1),
+  snapshot: PageSnapshotSchema,
+  changedByAgentId: z.string().optional(),
+  createdAt: z.string(),
+});
+export type PageVersion = z.infer<typeof PageVersionSchema>;
+
 // --- Workflow Run ---
 
 export const WorkflowRunStatusSchema = z.enum([

package/src/utils/error-tracker.ts

@@ -165,16 +165,70 @@ export function trackErrorFromJson(
   }
 }
 
+const MONTH_NAMES: Record<string, number> = {
+  jan: 0,
+  january: 0,
+  feb: 1,
+  february: 1,
+  mar: 2,
+  march: 2,
+  apr: 3,
+  april: 3,
+  may: 4,
+  jun: 5,
+  june: 5,
+  jul: 6,
+  july: 6,
+  aug: 7,
+  august: 7,
+  sep: 8,
+  sept: 8,
+  september: 8,
+  oct: 9,
+  october: 9,
+  nov: 10,
+  november: 10,
+  dec: 11,
+  december: 11,
+};
+
 /**
  * Parse a rate limit error message to extract a reset time, returning an ISO datetime string.
  * Handles patterns like:
  *   - "resets 3pm (UTC)" / "resets 3:30pm (UTC)"
+ *   - "resets May 14, 5pm (UTC)" / "resets May 14 5pm (UTC)"
  *   - "retry after 60 seconds" / "wait 120 seconds"
  *   - "retry after 2 minutes"
  * Returns undefined if no parseable reset time is found.
  */
 export function parseRateLimitResetTime(errorMessage: string): string | undefined {
-  // Pattern 1: "resets <time> (UTC)" — e.g. "resets 3pm (UTC)", "resets 3:30pm (UTC)"
+  // Pattern 1a: "resets <Month> <day>[,] <time> (UTC)" — e.g. "resets May 14, 5pm (UTC)"
+  const datedMatch = errorMessage.match(
+    /resets?\s+([A-Za-z]+)\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(?\s*UTC\s*\)?/i,
+  );
+  if (datedMatch) {
+    const monthIdx = MONTH_NAMES[datedMatch[1]!.toLowerCase()];
+    if (monthIdx !== undefined) {
+      const day = Number.parseInt(datedMatch[2]!, 10);
+      let hours = Number.parseInt(datedMatch[3]!, 10);
+      const minutes = datedMatch[4] ? Number.parseInt(datedMatch[4], 10) : 0;
+      const ampm = datedMatch[5]!.toLowerCase();
+      if (ampm === "pm" && hours !== 12) hours += 12;
+      if (ampm === "am" && hours === 12) hours = 0;
+
+      const now = new Date();
+      let year = now.getUTCFullYear();
+      let resetDate = new Date(Date.UTC(year, monthIdx, day, hours, minutes, 0));
+      // If the parsed date is in the past (date wrapped around year-end), assume next year.
+      if (resetDate.getTime() <= now.getTime()) {
+        year += 1;
+        resetDate = new Date(Date.UTC(year, monthIdx, day, hours, minutes, 0));
+      }
+      return resetDate.toISOString();
+    }
+  }
+
+  // Pattern 1b: "resets <time> (UTC)" — e.g. "resets 3pm (UTC)", "resets 3:30pm (UTC)"
   const resetTimeMatch = errorMessage.match(
     /resets?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(?\s*UTC\s*\)?/i,
   );