@desplega.ai/agent-swarm 1.78.1 → 1.79.1

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/kv/index.ts

@@ -0,0 +1,5 @@
+export { registerKvDeleteTool } from "./kv-delete";
+export { registerKvGetTool } from "./kv-get";
+export { registerKvIncrTool } from "./kv-incr";
+export { registerKvListTool } from "./kv-list";
+export { registerKvSetTool } from "./kv-set";

package/src/tools/kv/kv-delete.ts

@@ -0,0 +1,89 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteKv, getAgentById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvKeySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+function authError(namespace: string, info: { agentId: string | undefined }): string | null {
+  if (namespace.startsWith("task:page:")) {
+    return "task:page:* writes require a page-proxy request, not an MCP call";
+  }
+  if (namespace.startsWith("task:agent:")) {
+    const target = namespace.slice("task:agent:".length);
+    if (info.agentId && target === info.agentId) return null;
+    if (info.agentId) {
+      const agent = getAgentById(info.agentId);
+      if (agent?.isLead) return null;
+    }
+    return "writes to another agent's namespace require lead";
+  }
+  return null;
+}
+
+export const registerKvDeleteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-delete",
+    {
+      title: "KV Delete",
+      description:
+        "Remove a key from the swarm KV store. Returns whether a row was actually deleted. Namespace defaults to your current context.",
+      annotations: { idempotentHint: true },
+
+      inputSchema: z.object({
+        key: KvKeySchema,
+        namespace: KvNamespaceSchema.optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        deleted: z.boolean().optional(),
+      }),
+    },
+    async ({ key, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+      const authErr = authError(resolved.namespace, { agentId: requestInfo.agentId });
+      if (authErr) {
+        return {
+          content: [{ type: "text", text: authErr }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: authErr,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+      const deleted = deleteKv(resolved.namespace, key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: deleted
+              ? `Deleted "${key}" from "${resolved.namespace}".`
+              : `No entry to delete at "${key}" in "${resolved.namespace}".`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: deleted ? "deleted" : "not found",
+          namespace: resolved.namespace,
+          deleted,
+        },
+      };
+    },
+  );
+};

package/src/tools/kv/kv-get.ts

@@ -0,0 +1,64 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getKv } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvKeySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+export const registerKvGetTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-get",
+    {
+      title: "KV Get",
+      description:
+        "Read a key from the swarm KV store. Returns the entry or null if missing/expired. Namespace defaults to your current context (Slack thread / PR / Linear issue when invoked from a task; otherwise your agent scratchpad).",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        key: KvKeySchema.describe("KV key (≤512 chars, [a-zA-Z0-9._:/-])."),
+        namespace: KvNamespaceSchema.optional().describe(
+          "Optional explicit namespace. Defaults to the caller's contextKey.",
+        ),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entry: KvEntrySchema.nullable().optional(),
+      }),
+    },
+    async ({ key, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+
+      const entry = getKv(resolved.namespace, key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: entry
+              ? `Found "${key}" in "${resolved.namespace}".`
+              : `No entry for "${key}" in "${resolved.namespace}".`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: entry ? "ok" : "not found",
+          namespace: resolved.namespace,
+          entry: entry ?? null,
+        },
+      };
+    },
+  );
+};

package/src/tools/kv/kv-incr.ts

@@ -0,0 +1,116 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, incrKv, KvTypeCollisionError } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvKeySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+function authError(namespace: string, info: { agentId: string | undefined }): string | null {
+  if (namespace.startsWith("task:page:")) {
+    return "task:page:* writes require a page-proxy request, not an MCP call";
+  }
+  if (namespace.startsWith("task:agent:")) {
+    const target = namespace.slice("task:agent:".length);
+    if (info.agentId && target === info.agentId) return null;
+    if (info.agentId) {
+      const agent = getAgentById(info.agentId);
+      if (agent?.isLead) return null;
+    }
+    return "writes to another agent's namespace require lead";
+  }
+  return null;
+}
+
+export const registerKvIncrTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-incr",
+    {
+      title: "KV Incr",
+      description:
+        "Atomically increment an integer KV entry. Creates the entry (set to `by`) if it doesn't exist or has expired. Fails if the existing value_type is not 'integer' (use kv-delete first if you want to switch).",
+      annotations: {},
+
+      inputSchema: z.object({
+        key: KvKeySchema,
+        by: z
+          .number()
+          .int()
+          .optional()
+          .describe("Increment (or decrement when negative). Default: 1."),
+        namespace: KvNamespaceSchema.optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entry: KvEntrySchema.optional(),
+      }),
+    },
+    async ({ key, by, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+      const authErr = authError(resolved.namespace, { agentId: requestInfo.agentId });
+      if (authErr) {
+        return {
+          content: [{ type: "text", text: authErr }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: authErr,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+      try {
+        const entry = incrKv(resolved.namespace, key, by ?? 1);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `"${key}" now ${entry.value} in "${resolved.namespace}".`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: "ok",
+            namespace: resolved.namespace,
+            entry,
+          },
+        };
+      } catch (err) {
+        if (err instanceof KvTypeCollisionError) {
+          return {
+            content: [{ type: "text", text: err.message }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: err.message,
+              namespace: resolved.namespace,
+            },
+          };
+        }
+        const msg = err instanceof Error ? err.message : "INCR failed";
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: msg,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/kv/kv-list.ts

@@ -0,0 +1,81 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { countKv, listKv } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+const MAX_KV_LIST_LIMIT = 1000;
+
+export const registerKvListTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-list",
+    {
+      title: "KV List",
+      description:
+        "List KV entries in the resolved namespace (optionally filtered by key prefix). Expired entries are filtered out. Pagination via limit/offset (limit capped at 1000).",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        prefix: z.string().optional().describe("Key prefix to filter on."),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .max(MAX_KV_LIST_LIMIT)
+          .optional()
+          .describe("Max entries to return (default 100, max 1000)."),
+        offset: z.number().int().nonnegative().optional(),
+        namespace: KvNamespaceSchema.optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entries: z.array(KvEntrySchema).optional(),
+        total: z.number().optional(),
+      }),
+    },
+    async ({ prefix, limit, offset, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+      const effectiveLimit = Math.min(limit ?? 100, MAX_KV_LIST_LIMIT);
+      const effectivePrefix = prefix && prefix.length > 0 ? prefix : undefined;
+      const entries = listKv(resolved.namespace, {
+        prefix: effectivePrefix,
+        limit: effectiveLimit,
+        offset: offset ?? 0,
+      });
+      const total = countKv(resolved.namespace, { prefix: effectivePrefix });
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              entries.length === 0
+                ? `No entries in "${resolved.namespace}".`
+                : `Found ${entries.length} of ${total} entries in "${resolved.namespace}".`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: "ok",
+          namespace: resolved.namespace,
+          entries,
+          total,
+        },
+      };
+    },
+  );
+};