@desplega.ai/agent-swarm 1.78.1 → 1.79.0

package/src/pages/version.ts

@@ -0,0 +1,44 @@
+import { createPageVersion, getPage, getPageVersions } from "../be/db";
+import type { PageSnapshot, PageVersion } from "../types";
+
+/**
+ * Create a version snapshot of a page's current state.
+ *
+ * Call this BEFORE applying an update to preserve the pre-update state.
+ * Mirrors `snapshotWorkflow` (src/workflows/version.ts:13-44).
+ *
+ * 1. Load current page state
+ * 2. Get max version number for this page (page_versions ORDER BY version DESC)
+ * 3. Insert page_versions row with version+1 and the pre-update snapshot
+ *
+ * Throws on missing parent. Callers in HTTP handlers wrap this in a try/catch
+ * with an empty catch — snapshot failure should not block the update (matches
+ * the workflow pattern at src/http/workflows.ts:483-486).
+ */
+export function snapshotPage(pageId: string, changedByAgentId?: string): PageVersion {
+  const page = getPage(pageId);
+  if (!page) {
+    throw new Error(`Page ${pageId} not found — cannot create snapshot`);
+  }
+
+  const existingVersions = getPageVersions(pageId);
+  const maxVersion = existingVersions.length > 0 ? existingVersions[0]!.version : 0;
+  const nextVersion = maxVersion + 1;
+
+  const snapshot: PageSnapshot = {
+    title: page.title,
+    description: page.description,
+    contentType: page.contentType,
+    authMode: page.authMode,
+    passwordHash: page.passwordHash,
+    body: page.body,
+    needsCredentials: page.needsCredentials,
+  };
+
+  return createPageVersion({
+    pageId,
+    version: nextVersion,
+    snapshot,
+    changedByAgentId,
+  });
+}

package/src/prompts/session-templates.ts

@@ -297,6 +297,20 @@ agent-fs comment add docs/spec.md --body "Needs clarification on auth flow"
 agent-fs comment list docs/spec.md
 \`\`\`
 
+### Sharing agent-fs files with humans
+
+To give a human a direct link to a file, build the URL from the live host
+(env-var driven, never hardcode):
+
+\`\`\`
+\${AGENT_FS_LIVE_URL}/file/~/<org_id>/<drive_id>/<file_path>
+\`\`\`
+
+\`AGENT_FS_LIVE_URL\` defaults to \`https://live.agent-fs.dev\` if not set.
+\`<org_id>\` and \`<drive_id>\` come from the file's \`agent-fs stat <path> --json\`
+output (or the agent-fs CLI returns them on write). Use the **shared** drive
+id for files humans should review.
+
 Key conventions:
 - **Personal drive**: thoughts/{type}/YYYY-MM-DD-topic.md (plans, research, brainstorms)
 - **Shared drive**: thoughts/{{agentId}}/{type}/YYYY-MM-DD-topic.md (same structure, namespaced by your ID)
@@ -442,6 +456,41 @@ registerTemplate({
 Agents can serve interactive web content (HTML pages, dashboards, approval flows) via public URLs using localtunnel.
 Use the \`/artifacts\` skill for detailed instructions, examples, and API reference.
 Artifact content should be stored in \`/workspace/personal/artifacts/\` (persisted across sessions).
+
+For lightweight static reports / dashboards (HTML or JSON), prefer the
+\`create_page\` MCP tool (\`pages\` skill) — it stores in SQLite and serves at
+\`/p/:id\` without a PM2 process or tunnel.
+`,
+  variables: [],
+  category: "system",
+});
+
+registerTemplate({
+  eventType: "system.agent.share_urls",
+  header: "",
+  defaultBody: `
+### Share URLs (read from env, never hardcode)
+
+When you emit a link meant for a human or another agent — a page, artifact,
+agent-fs file, or any external URL — read the host from env. Hardcoded hosts
+break across deployments.
+
+| Env var | Purpose | Prod example |
+|---|---|---|
+| \`MCP_BASE_URL\` | API origin. Use for \`/p/:id\` direct page links and any \`/api/*\` curl examples. | \`https://api.example-swarm.dev\` |
+| \`APP_URL\` | SPA origin. Default share target for pages: \`\${APP_URL}/pages/:id\`. Append \`?mode=full\` for a maximized view (slim header + body fills viewport). | \`https://app.example-swarm.dev\` |
+| \`SWARM_URL\` | Bare host (no scheme). Use in copy / Slack messages that need just the domain. | \`app.example-swarm.dev\` |
+| \`AGENT_FS_LIVE_URL\` | agent-fs live origin. Share files via \`\${AGENT_FS_LIVE_URL}/file/~/<org_id>/<drive_id>/<file_path>\`. Defaults to \`https://live.agent-fs.dev\` if unset. | \`https://live.agent-fs.dev\` |
+
+**Page share patterns** (most common):
+- Default: \`\${APP_URL}/pages/:id\` — opens the SPA with chrome.
+- Full / standalone: \`\${APP_URL}/pages/:id?mode=full\` — hides sidebar/header; slim row with title + Exit-Full.
+- Direct API (no SPA): \`\${MCP_BASE_URL}/p/:id\` — HTML inlines; JSON 302→SPA.
+
+**agent-fs share pattern**: \`\${AGENT_FS_LIVE_URL}/file/~/<org_id>/<drive_id>/<file_path>\`.
+
+If a required env var is missing, **surface that to the user** — never fall
+back to a localhost value or invent a host when shipping a share link.
 `,
   variables: [],
   category: "system",
@@ -493,6 +542,7 @@ registerTemplate({
 {{@template[system.agent.context_mode]}}
 
 {{@template[system.agent.system]}}
+{{@template[system.agent.share_urls]}}
 {{@template[system.agent.code_quality]}}`,
   variables: [
     { name: "role", description: "The agent's role" },
@@ -513,6 +563,7 @@ registerTemplate({
 {{@template[system.agent.context_mode]}}
 
 {{@template[system.agent.system]}}
+{{@template[system.agent.share_urls]}}
 {{@template[system.agent.code_quality]}}`,
   variables: [
     { name: "role", description: "The agent's role" },

package/src/server.ts

@@ -5,6 +5,7 @@ import { registerCancelTaskTool } from "./tools/cancel-task";
 import { registerContextDiffTool } from "./tools/context-diff";
 import { registerContextHistoryTool } from "./tools/context-history";
 import { registerCreateChannelTool } from "./tools/create-channel";
+import { registerCreatePageTool } from "./tools/create-page";
 import { registerDbQueryTool } from "./tools/db-query";
 import { registerDeleteChannelTool } from "./tools/delete-channel";
 import { registerGetSwarmTool } from "./tools/get-swarm";
@@ -120,7 +121,7 @@ import {
 
 // Capability-based feature flags
 // Default: all capabilities enabled
-const DEFAULT_CAPABILITIES = "core,task-pool,profiles,services,scheduling,memory,workflows";
+const DEFAULT_CAPABILITIES = "core,task-pool,profiles,services,scheduling,memory,workflows,pages";
 const CAPABILITIES = new Set(
   (process.env.CAPABILITIES || DEFAULT_CAPABILITIES).split(",").map((s) => s.trim()),
 );
@@ -284,6 +285,14 @@ export function createServer() {
   registerSkillSyncRemoteTool(server);
   registerSkillPublishTool(server);
 
+  // Pages capability - DB-backed lightweight artifacts (HTML / JSON specs).
+  // Enabled by default (added to DEFAULT_CAPABILITIES in step-9 of the
+  // db-backed-pages plan). Operators can disable via explicit
+  // `CAPABILITIES=...` env without `pages`.
+  if (hasCapability("pages")) {
+    registerCreatePageTool(server);
+  }
+
   // MCP Servers - always registered
   registerMcpServerCreateTool(server);
   registerMcpServerUpdateTool(server);

package/src/tests/artifact-commands.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Regression test for the `/api/services` response-shape bug in
+ * `src/commands/artifact.ts` (artifactList / artifactStop).
+ *
+ * The endpoint returns `{ services: [...] }`, but earlier the code
+ * cast the JSON as a bare `Array<...>` and crashed with
+ * `services.filter is not a function`.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+import { runArtifact } from "../commands/artifact";
+
+const originalFetch = globalThis.fetch;
+const originalLog = console.log;
+const originalError = console.error;
+
+let capturedOut: string[] = [];
+let capturedErr: string[] = [];
+
+beforeAll(() => {
+  console.log = (...args: unknown[]) => {
+    capturedOut.push(args.map(String).join(" "));
+  };
+  console.error = (...args: unknown[]) => {
+    capturedErr.push(args.map(String).join(" "));
+  };
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  capturedOut = [];
+  capturedErr = [];
+});
+
+afterAll(() => {
+  globalThis.fetch = originalFetch;
+  console.log = originalLog;
+  console.error = originalError;
+});
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("runArtifact('list')", () => {
+  test("handles wrapped { services: [] } without throwing", async () => {
+    globalThis.fetch = mock(() => Promise.resolve(jsonResponse({ services: [] })));
+
+    await expect(runArtifact("list", { additionalArgs: [] })).resolves.toBeUndefined();
+    expect(capturedOut.join("\n")).toContain("No active artifacts");
+    expect(capturedErr.join("\n")).not.toContain("services.filter");
+  });
+
+  test("renders artifact rows from { services: [...] }", async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        jsonResponse({
+          services: [
+            {
+              name: "artifact-testart",
+              agentId: "agent-xyz",
+              status: "healthy",
+              metadata: {
+                type: "artifact",
+                artifactName: "testart",
+                port: 4242,
+                publicUrl: "https://testart.loca.lt",
+              },
+            },
+          ],
+        }),
+      ),
+    );
+
+    await expect(runArtifact("list", { additionalArgs: [] })).resolves.toBeUndefined();
+    const out = capturedOut.join("\n");
+    expect(out).toContain("testart");
+    expect(out).toContain("4242");
+    expect(out).toContain("https://testart.loca.lt");
+    expect(out).toContain("healthy");
+  });
+
+  test("falls back to [] when response omits services key", async () => {
+    globalThis.fetch = mock(() => Promise.resolve(jsonResponse({})));
+
+    await expect(runArtifact("list", { additionalArgs: [] })).resolves.toBeUndefined();
+    expect(capturedOut.join("\n")).toContain("No active artifacts");
+  });
+});

package/src/tests/artifact-sdk.test.ts

@@ -64,48 +64,48 @@ describe("BROWSER_SDK_JS", () => {
     expect(BROWSER_SDK_JS).toContain("class SwarmSDK");
   });
 
-  test("contains all expected API methods", () => {
-    const expectedMethods = [
-      "createTask",
-      "getTasks",
-      "getTaskDetails",
-      "storeProgress",
-      "postMessage",
-      "readMessages",
-      "getSwarm",
-      "listServices",
-      "slackReply",
+  test("exposes the seven canonical domains", () => {
+    const expectedDomains = [
+      "this.tasks",
+      "this.agents",
+      "this.events",
+      "this.memory",
+      "this.repos",
+      "this.schedules",
+      "this.approvalRequests",
     ];
-    for (const method of expectedMethods) {
-      expect(BROWSER_SDK_JS).toContain(method);
+    for (const domain of expectedDomains) {
+      expect(BROWSER_SDK_JS).toContain(domain);
     }
   });
 
-  test("assigns SwarmSDK to window", () => {
+  test("removed domains are NOT exposed (messages, services, slack)", () => {
+    const removed = ["this.messages", "this.services", "this.slack", "postMessage", "readMessages"];
+    for (const r of removed) {
+      expect(BROWSER_SDK_JS).not.toContain(r);
+    }
+  });
+
+  test("assigns SwarmSDK class + swarmSdk singleton to window", () => {
     expect(BROWSER_SDK_JS).toContain("window.SwarmSDK = SwarmSDK");
+    expect(BROWSER_SDK_JS).toContain("window.swarmSdk = new SwarmSDK()");
   });
 
-  test("uses correct proxy API paths", () => {
-    expect(BROWSER_SDK_JS).toContain("/@swarm/api/tasks");
-    expect(BROWSER_SDK_JS).toContain("/@swarm/api/agents");
-    expect(BROWSER_SDK_JS).toContain("/@swarm/api/messages");
-    expect(BROWSER_SDK_JS).toContain("/@swarm/api/services");
-    expect(BROWSER_SDK_JS).toContain("/@swarm/api/slack/reply");
+  test("routes calls through the /@swarm/api/* proxy", () => {
+    expect(BROWSER_SDK_JS).toContain("const base = '/@swarm/api'");
+    // Sentinel endpoints — one per domain.
+    expect(BROWSER_SDK_JS).toContain("'/tasks'");
+    expect(BROWSER_SDK_JS).toContain("'/agents'");
+    expect(BROWSER_SDK_JS).toContain("'/events'");
+    expect(BROWSER_SDK_JS).toContain("'/memory/search'");
+    expect(BROWSER_SDK_JS).toContain("'/repos'");
+    expect(BROWSER_SDK_JS).toContain("'/schedules'");
+    expect(BROWSER_SDK_JS).toContain("'/approval-requests'");
   });
 
   test("fetches config on construction", () => {
     expect(BROWSER_SDK_JS).toContain("fetch('/@swarm/config')");
   });
-
-  test("has _post helper with JSON content-type", () => {
-    expect(BROWSER_SDK_JS).toContain("_post(url, body)");
-    expect(BROWSER_SDK_JS).toContain("'Content-Type': 'application/json'");
-    expect(BROWSER_SDK_JS).toContain("JSON.stringify(body)");
-  });
-
-  test("has _get helper", () => {
-    expect(BROWSER_SDK_JS).toContain("_get(url)");
-  });
 });
 
 // ─── createArtifactServer factory tests ──────────────────────────────────
@@ -536,27 +536,29 @@ describe("artifact CLI command", () => {
           const url = new URL(req.url);
           if (url.pathname === "/api/services") {
             return new Response(
-              JSON.stringify([
-                {
-                  id: "svc-1",
-                  name: "artifact-dashboard",
-                  agentId: "agent-123",
-                  status: "healthy",
-                  metadata: {
-                    type: "artifact",
-                    artifactName: "dashboard",
-                    port: 3001,
-                    publicUrl: "https://test.lt.example.com",
+              JSON.stringify({
+                services: [
+                  {
+                    id: "svc-1",
+                    name: "artifact-dashboard",
+                    agentId: "agent-123",
+                    status: "healthy",
+                    metadata: {
+                      type: "artifact",
+                      artifactName: "dashboard",
+                      port: 3001,
+                      publicUrl: "https://test.lt.example.com",
+                    },
                   },
-                },
-                {
-                  id: "svc-2",
-                  name: "some-other-service",
-                  agentId: "agent-456",
-                  status: "healthy",
-                  metadata: { type: "web" },
-                },
-              ]),
+                  {
+                    id: "svc-2",
+                    name: "some-other-service",
+                    agentId: "agent-456",
+                    status: "healthy",
+                    metadata: { type: "web" },
+                  },
+                ],
+              }),
             );
           }
           return new Response("Not found", { status: 404 });
@@ -593,7 +595,7 @@ describe("artifact CLI command", () => {
       const mockPort = await getAvailablePort();
       const mockServer = Bun.serve({
         port: mockPort,
-        fetch: () => new Response(JSON.stringify([])),
+        fetch: () => new Response(JSON.stringify({ services: [] })),
       });
 
       const origEnv = { ...process.env };
@@ -626,22 +628,24 @@ describe("artifact CLI command", () => {
         port: mockPort,
         fetch: () =>
           new Response(
-            JSON.stringify([
-              {
-                id: "s1",
-                name: "web-server",
-                agentId: "a1",
-                status: "healthy",
-                metadata: { type: "web" },
-              },
-              {
-                id: "s2",
-                name: "api-server",
-                agentId: "a2",
-                status: "healthy",
-                metadata: {},
-              },
-            ]),
+            JSON.stringify({
+              services: [
+                {
+                  id: "s1",
+                  name: "web-server",
+                  agentId: "a1",
+                  status: "healthy",
+                  metadata: { type: "web" },
+                },
+                {
+                  id: "s2",
+                  name: "api-server",
+                  agentId: "a2",
+                  status: "healthy",
+                  metadata: {},
+                },
+              ],
+            }),
           ),
       });
 
@@ -682,13 +686,15 @@ describe("artifact CLI command", () => {
           const url = new URL(req.url);
           if (req.method === "GET" && url.pathname === "/api/services") {
             return new Response(
-              JSON.stringify([
-                {
-                  id: "svc-to-delete",
-                  name: "artifact-my-report",
-                  metadata: { type: "artifact", artifactName: "my-report" },
-                },
-              ]),
+              JSON.stringify({
+                services: [
+                  {
+                    id: "svc-to-delete",
+                    name: "artifact-my-report",
+                    metadata: { type: "artifact", artifactName: "my-report" },
+                  },
+                ],
+              }),
             );
           }
           if (req.method === "DELETE" && url.pathname.startsWith("/api/services/")) {

package/src/tests/create-page-tool.test.ts

@@ -0,0 +1,197 @@
+/**
+ * `create_page` MCP tool — unit-level coverage. Registers the tool against
+ * a fresh `McpServer`, pulls the handler out of the SDK's registry, and
+ * invokes it directly with a stubbed agent-id `requestInfo`.
+ *
+ * Verifies:
+ *   - first-call path: creates a row in `pages`, returns `{id, version=1, app_url, api_url}`
+ *   - upsert path: second call with the same slug bumps the edit-counter
+ *     and writes a version row
+ *   - capability gate: tool is registered when `CAPABILITIES` contains
+ *     `pages`, NOT registered when missing (verified via `createServer`)
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, getPageBySlug, getPageVersions, initDb } from "../be/db";
+import { registerCreatePageTool } from "../tools/create-page";
+
+const TEST_DB_PATH = "./test-create-page-tool.sqlite";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<unknown>;
+};
+
+function buildServer() {
+  const server = new McpServer({ name: "create-page-test", version: "1.0.0" });
+  registerCreatePageTool(server);
+  const registered = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+  const tool = registered.create_page;
+  if (!tool) throw new Error("create_page tool not registered");
+  return tool;
+}
+
+describe("create_page MCP tool", () => {
+  const agentId = crypto.randomUUID();
+  const fakeMeta = {
+    sessionId: "session-1",
+    requestInfo: { headers: { "x-agent-id": agentId } },
+  };
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    // The tool reads MCP_BASE_URL / APP_URL when building share URLs.
+    process.env.MCP_BASE_URL = "http://test-api:9999";
+    process.env.APP_URL = "http://test-app:5274";
+  });
+
+  afterAll(async () => {
+    closeDb();
+    delete process.env.MCP_BASE_URL;
+    delete process.env.APP_URL;
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+  });
+
+  test("first call creates a row + returns shareable URLs", async () => {
+    const tool = buildServer();
+    const result = (await tool.handler(
+      {
+        title: "Hello Page",
+        body: "<h1>hello</h1>",
+        contentType: "text/html",
+        authMode: "public",
+      },
+      fakeMeta,
+    )) as {
+      structuredContent: {
+        id: string;
+        version: number;
+        app_url: string;
+        api_url: string;
+        yourAgentId: string;
+      };
+    };
+
+    expect(result.structuredContent.id).toMatch(/^[0-9a-f]{32}$/);
+    expect(result.structuredContent.version).toBe(1);
+    expect(result.structuredContent.api_url).toBe(
+      `http://test-api:9999/p/${result.structuredContent.id}`,
+    );
+    expect(result.structuredContent.app_url).toBe(
+      `http://test-app:5274/pages/${result.structuredContent.id}`,
+    );
+    expect(result.structuredContent.yourAgentId).toBe(agentId);
+
+    // DB row exists with the auto-slug from the title.
+    const row = getPageBySlug(agentId, "hello-page");
+    expect(row).not.toBeNull();
+    expect(row!.body).toBe("<h1>hello</h1>");
+  });
+
+  test("re-running with the same slug upserts + bumps edit-counter", async () => {
+    const tool = buildServer();
+
+    const first = (await tool.handler(
+      {
+        title: "Upsert Page",
+        slug: "upsert",
+        body: "v0",
+        contentType: "text/html",
+        authMode: "public",
+      },
+      fakeMeta,
+    )) as { structuredContent: { id: string; version: number } };
+    expect(first.structuredContent.version).toBe(1);
+
+    const second = (await tool.handler(
+      {
+        title: "Upsert Page",
+        slug: "upsert",
+        body: "v1",
+        contentType: "text/html",
+        authMode: "public",
+      },
+      fakeMeta,
+    )) as { structuredContent: { id: string; version: number } };
+    expect(second.structuredContent.id).toBe(first.structuredContent.id);
+    expect(second.structuredContent.version).toBe(2);
+
+    // Version row holds the PRE-update body.
+    const versions = getPageVersions(first.structuredContent.id);
+    expect(versions).toHaveLength(1);
+    expect(versions[0]!.snapshot.body).toBe("v0");
+
+    // Parent now holds the new body.
+    const row = getPageBySlug(agentId, "upsert");
+    expect(row?.body).toBe("v1");
+  });
+
+  test("missing X-Agent-ID returns an error result", async () => {
+    const tool = buildServer();
+    const result = (await tool.handler(
+      {
+        title: "Anon",
+        body: "x",
+        contentType: "text/html",
+        authMode: "public",
+      },
+      { sessionId: "s", requestInfo: { headers: {} } },
+    )) as { isError?: boolean };
+    expect(result.isError).toBe(true);
+  });
+
+  test("password is hashed (not stored verbatim)", async () => {
+    const tool = buildServer();
+    await tool.handler(
+      {
+        title: "Pw",
+        slug: "pw-tool",
+        body: "secret",
+        contentType: "text/html",
+        authMode: "password",
+        password: "open-sesame",
+      },
+      fakeMeta,
+    );
+    const row = getPageBySlug(agentId, "pw-tool");
+    expect(row?.passwordHash).toBeDefined();
+    expect(row?.passwordHash).not.toBe("open-sesame");
+    expect(await Bun.password.verify("open-sesame", row!.passwordHash!)).toBe(true);
+  });
+});
+
+describe("create_page MCP tool capability gating", () => {
+  test("not registered without 'pages' capability; registered with it", async () => {
+    // Save + clear env then load the server module fresh.
+    const orig = process.env.CAPABILITIES;
+    try {
+      // Default capabilities don't include 'pages' (step-3 enforced).
+      process.env.CAPABILITIES = "core,task-pool,profiles,services,scheduling,memory,workflows";
+      // Force a fresh module evaluation so the capability check re-runs.
+      delete require.cache[require.resolve("../server")];
+      const without = await import("../server");
+      expect(without.hasCapability("pages")).toBe(false);
+
+      process.env.CAPABILITIES =
+        "core,task-pool,profiles,services,scheduling,memory,workflows,pages";
+      delete require.cache[require.resolve("../server")];
+      const withPages = await import("../server");
+      expect(withPages.hasCapability("pages")).toBe(true);
+    } finally {
+      if (orig === undefined) delete process.env.CAPABILITIES;
+      else process.env.CAPABILITIES = orig;
+      delete require.cache[require.resolve("../server")];
+    }
+  });
+});