@desplega.ai/agent-swarm 1.78.0 → 1.79.0

package/src/be/db.ts

@@ -38,6 +38,11 @@ import type {
   McpServerScope,
   McpServerTransport,
   McpServerWithInstallInfo,
+  Page,
+  PageAuthMode,
+  PageContentType,
+  PageSnapshot,
+  PageVersion,
   PricingProvider,
   PricingRow,
   PricingTokenClass,
@@ -6237,6 +6242,240 @@ export function getWorkflowVersion(workflowId: string, version: number): Workflo
   return row ? rowToWorkflowVersion(row) : null;
 }
 
+// ============================================================================
+// Pages CRUD + version history
+// ----------------------------------------------------------------------------
+// DB-backed lightweight artifacts. Mirrors the workflow versioning pattern:
+// parent table `pages` holds the CURRENT state, history table `page_versions`
+// holds pre-update snapshots. snapshotPage() (src/pages/version.ts) MUST be
+// called BEFORE updatePage() so the snapshot freezes pre-update content.
+// ============================================================================
+
+type PageRow = {
+  id: string;
+  agentId: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  contentType: string;
+  authMode: string;
+  passwordHash: string | null;
+  body: string;
+  needsCredentials: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+function rowToPage(row: PageRow): Page {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    slug: row.slug,
+    title: row.title,
+    description: row.description ?? undefined,
+    contentType: row.contentType as PageContentType,
+    authMode: row.authMode as PageAuthMode,
+    passwordHash: row.passwordHash ?? undefined,
+    body: row.body,
+    needsCredentials: row.needsCredentials
+      ? (JSON.parse(row.needsCredentials) as string[])
+      : undefined,
+    createdAt: normalizeDateRequired(row.createdAt),
+    updatedAt: normalizeDateRequired(row.updatedAt),
+  };
+}
+
+export function createPage(data: {
+  agentId: string;
+  slug: string;
+  title: string;
+  description?: string;
+  contentType: PageContentType;
+  authMode: PageAuthMode;
+  passwordHash?: string;
+  body: string;
+  needsCredentials?: string[];
+}): Page {
+  const row = getDb()
+    .prepare<
+      PageRow,
+      [string, string, string, string | null, string, string, string | null, string, string | null]
+    >(
+      `INSERT INTO pages (agentId, slug, title, description, contentType, authMode, passwordHash, body, needsCredentials)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+    )
+    .get(
+      data.agentId,
+      data.slug,
+      data.title,
+      data.description ?? null,
+      data.contentType,
+      data.authMode,
+      data.passwordHash ?? null,
+      data.body,
+      data.needsCredentials ? JSON.stringify(data.needsCredentials) : null,
+    );
+  if (!row) throw new Error("Failed to create page");
+  return rowToPage(row);
+}
+
+export function getPage(id: string): Page | null {
+  const row = getDb().prepare<PageRow, [string]>("SELECT * FROM pages WHERE id = ?").get(id);
+  return row ? rowToPage(row) : null;
+}
+
+export function getPageBySlug(agentId: string, slug: string): Page | null {
+  const row = getDb()
+    .prepare<PageRow, [string, string]>("SELECT * FROM pages WHERE agentId = ? AND slug = ?")
+    .get(agentId, slug);
+  return row ? rowToPage(row) : null;
+}
+
+export function listPagesByAgent(agentId: string, limit = 100, offset = 0): Page[] {
+  return getDb()
+    .prepare<PageRow, [string, number, number]>(
+      "SELECT * FROM pages WHERE agentId = ? ORDER BY updatedAt DESC LIMIT ? OFFSET ?",
+    )
+    .all(agentId, limit, offset)
+    .map(rowToPage);
+}
+
+export function listAllPages(limit = 100, offset = 0): Page[] {
+  return getDb()
+    .prepare<PageRow, [number, number]>(
+      "SELECT * FROM pages ORDER BY updatedAt DESC LIMIT ? OFFSET ?",
+    )
+    .all(limit, offset)
+    .map(rowToPage);
+}
+
+/**
+ * Apply a patch to a page. Does NOT snapshot — caller must invoke
+ * `snapshotPage(id, agentId)` BEFORE calling this to preserve pre-update
+ * state (mirrors the workflow update pattern at src/http/workflows.ts:483).
+ *
+ * Always bumps `updatedAt` even if no other field changed (keeps the index
+ * useful for list ordering).
+ */
+export function updatePage(
+  id: string,
+  data: {
+    title?: string;
+    description?: string | null;
+    contentType?: PageContentType;
+    authMode?: PageAuthMode;
+    passwordHash?: string | null;
+    body?: string;
+    needsCredentials?: string[] | null;
+    slug?: string;
+  },
+): Page | null {
+  const updates: string[] = [];
+  const params: (string | number | null)[] = [];
+  if (data.title !== undefined) {
+    updates.push("title = ?");
+    params.push(data.title);
+  }
+  if (data.description !== undefined) {
+    updates.push("description = ?");
+    params.push(data.description ?? null);
+  }
+  if (data.contentType !== undefined) {
+    updates.push("contentType = ?");
+    params.push(data.contentType);
+  }
+  if (data.authMode !== undefined) {
+    updates.push("authMode = ?");
+    params.push(data.authMode);
+  }
+  if (data.passwordHash !== undefined) {
+    updates.push("passwordHash = ?");
+    params.push(data.passwordHash ?? null);
+  }
+  if (data.body !== undefined) {
+    updates.push("body = ?");
+    params.push(data.body);
+  }
+  if (data.needsCredentials !== undefined) {
+    updates.push("needsCredentials = ?");
+    params.push(data.needsCredentials ? JSON.stringify(data.needsCredentials) : null);
+  }
+  if (data.slug !== undefined) {
+    updates.push("slug = ?");
+    params.push(data.slug);
+  }
+  if (updates.length === 0) return getPage(id);
+  updates.push("updatedAt = ?");
+  params.push(new Date().toISOString());
+  params.push(id);
+  const row = getDb()
+    .prepare<PageRow, (string | number | null)[]>(
+      `UPDATE pages SET ${updates.join(", ")} WHERE id = ? RETURNING *`,
+    )
+    .get(...params);
+  return row ? rowToPage(row) : null;
+}
+
+export function deletePage(id: string): boolean {
+  // ON DELETE CASCADE on page_versions.pageId handles history cleanup.
+  const result = getDb().run("DELETE FROM pages WHERE id = ?", [id]);
+  return result.changes > 0;
+}
+
+type PageVersionRow = {
+  id: string;
+  pageId: string;
+  version: number;
+  snapshot: string;
+  changedByAgentId: string | null;
+  createdAt: string;
+};
+
+function rowToPageVersion(row: PageVersionRow): PageVersion {
+  return {
+    id: row.id,
+    pageId: row.pageId,
+    version: row.version,
+    snapshot: JSON.parse(row.snapshot) as PageSnapshot,
+    changedByAgentId: row.changedByAgentId ?? undefined,
+    createdAt: normalizeDateRequired(row.createdAt),
+  };
+}
+
+export function createPageVersion(data: {
+  pageId: string;
+  version: number;
+  snapshot: PageSnapshot;
+  changedByAgentId?: string;
+}): PageVersion {
+  const row = getDb()
+    .prepare<PageVersionRow, [string, number, string, string | null]>(
+      `INSERT INTO page_versions (pageId, version, snapshot, changedByAgentId)
+       VALUES (?, ?, ?, ?) RETURNING *`,
+    )
+    .get(data.pageId, data.version, JSON.stringify(data.snapshot), data.changedByAgentId ?? null);
+  if (!row) throw new Error("Failed to create page version");
+  return rowToPageVersion(row);
+}
+
+export function getPageVersions(pageId: string): PageVersion[] {
+  return getDb()
+    .prepare<PageVersionRow, [string]>(
+      "SELECT * FROM page_versions WHERE pageId = ? ORDER BY version DESC",
+    )
+    .all(pageId)
+    .map(rowToPageVersion);
+}
+
+export function getPageVersion(pageId: string, version: number): PageVersion | null {
+  const row = getDb()
+    .prepare<PageVersionRow, [string, number]>(
+      "SELECT * FROM page_versions WHERE pageId = ? AND version = ?",
+    )
+    .get(pageId, version);
+  return row ? rowToPageVersion(row) : null;
+}
+
 // ============================================================================
 // Prompt Template Operations
 // ============================================================================

package/src/be/migrations/059_pages.sql

@@ -0,0 +1,34 @@
+-- DB-backed Pages (parent table) — lightweight artifacts stored in SQLite and
+-- served as HTML or JSON. Replaces PM2+localtunnel for static cases.
+--
+-- `body` stores agent-emitted content verbatim. For contentType='text/html',
+-- callers MAY pass either a fragment (`<h1>hi</h1>`) or a full document
+-- (`<!doctype html>...<html>...`). Step-3's `/p/:id` serving logic detects
+-- `<head>` and injects BROWSER_SDK_JS after it; if absent, it prepends.
+-- For contentType='application/json', the body is a JSON-render-compatible
+-- spec stored as a string (parsed at render time).
+--
+-- `needsCredentials` is reserved for follow-up credential capture work; the
+-- v1 renderer ignores it (Zod accepts, no UI prompt).
+--
+-- `authMode` CHECK constraint MUST stay in sync with PageAuthModeSchema in
+-- src/types.ts.
+
+CREATE TABLE IF NOT EXISTS pages (
+  id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  agentId      TEXT NOT NULL,
+  slug         TEXT NOT NULL,
+  title        TEXT NOT NULL,
+  description  TEXT,
+  contentType  TEXT NOT NULL CHECK (contentType IN ('text/html','application/json')),
+  authMode     TEXT NOT NULL DEFAULT 'public' CHECK (authMode IN ('public','authed','password')),
+  passwordHash TEXT,
+  body         TEXT NOT NULL,
+  needsCredentials TEXT,
+  createdAt    TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updatedAt    TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (agentId, slug)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pages_agentId ON pages(agentId);
+CREATE INDEX IF NOT EXISTS idx_pages_updatedAt ON pages(updatedAt DESC);

package/src/be/migrations/060_page_versions.sql

@@ -0,0 +1,19 @@
+-- DB-backed Pages (history table). Mirrors workflow_versions
+-- (008_workflow_redesign.sql:74-82) — parent table holds CURRENT state, this
+-- table holds the pre-update snapshot taken by snapshotPage() before each
+-- updatePage(). Head pointer is derived from MAX(version); no head_version
+-- column on the parent.
+--
+-- ON DELETE CASCADE: deleting a page removes its version history.
+
+CREATE TABLE IF NOT EXISTS page_versions (
+  id                  TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  pageId              TEXT NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+  version             INTEGER NOT NULL,
+  snapshot            TEXT NOT NULL,  -- JSON: PageSnapshot
+  changedByAgentId    TEXT,
+  createdAt           TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (pageId, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_page_versions_pageId ON page_versions(pageId);

package/src/commands/artifact.ts

@@ -154,12 +154,15 @@ async function artifactList() {
       process.exit(1);
     }
 
-    const services = (await res.json()) as Array<{
-      name: string;
-      agentId: string;
-      status: string;
-      metadata?: { type?: string; artifactName?: string; port?: number; publicUrl?: string };
-    }>;
+    const body = (await res.json()) as {
+      services?: Array<{
+        name: string;
+        agentId: string;
+        status: string;
+        metadata?: { type?: string; artifactName?: string; port?: number; publicUrl?: string };
+      }>;
+    };
+    const services = body.services ?? [];
 
     const artifacts = services.filter((s) => s.metadata?.type === "artifact");
 
@@ -214,11 +217,14 @@ async function artifactStop(args: ArtifactArgs) {
     });
 
     if (res.ok) {
-      const services = (await res.json()) as Array<{
-        id: string;
-        name: string;
-        metadata?: { type?: string; artifactName?: string };
-      }>;
+      const body = (await res.json()) as {
+        services?: Array<{
+          id: string;
+          name: string;
+          metadata?: { type?: string; artifactName?: string };
+        }>;
+      };
+      const services = body.services ?? [];
       const service = services.find(
         (s) => s.metadata?.type === "artifact" && s.metadata?.artifactName === name,
       );

package/src/http/index.ts

@@ -35,6 +35,9 @@ import { handleMcp } from "./mcp";
 import { handleMcpOAuth, startMcpOAuthPendingGc, stopMcpOAuthPendingGc } from "./mcp-oauth";
 import { handleMcpServers } from "./mcp-servers";
 import { handleMemory } from "./memory";
+import { handlePageProxy } from "./page-proxy";
+import { handlePages } from "./pages";
+import { handlePagesPublic } from "./pages-public";
 import { handlePoll } from "./poll";
 import { handlePricing } from "./pricing";
 import { handlePromptTemplates } from "./prompt-templates";
@@ -109,7 +112,7 @@ const httpServer = createHttpServer(async (req, res) => {
     console.error(`[HTTP] ❌ ${req.method} ${req.url} → Error: ${err.message}`);
   });
 
-  setCorsHeaders(res);
+  setCorsHeaders(req, res);
 
   // ── Core routes (OPTIONS, health, auth, /me, /cancelled-tasks, /ping, /close) ──
   if (await handleCore(req, res, req.headers["x-agent-id"] as string | undefined, apiKey)) return;
@@ -147,6 +150,9 @@ const httpServer = createHttpServer(async (req, res) => {
     () => handleMcpServers(req, res, pathSegments, queryParams),
     () => handleMcpOAuth(req, res, pathSegments, queryParams),
     () => handleMemory(req, res, pathSegments, myAgentId),
+    () => handlePagesPublic(req, res, pathSegments, queryParams),
+    () => handlePageProxy(req, res),
+    () => handlePages(req, res, pathSegments, queryParams, myAgentId),
     () => handleApiKeys(req, res, pathSegments, queryParams),
     () => handleHeartbeat(req, res, pathSegments),
     () => handleEvents(req, res, pathSegments, queryParams, myAgentId),

package/src/http/page-proxy.ts

@@ -0,0 +1,208 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { getPage } from "../be/db";
+import { extractAndVerifyCookie } from "../utils/page-session";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+/**
+ * `/@swarm/api/*` proxy. Cookie-gated equivalent of the artifact-sdk proxy
+ * (src/artifact-sdk/server.ts:42-69), but lives on the MAIN API server and
+ * authenticates via the page-session cookie instead of basic-auth + a per-
+ * artifact tunnel.
+ *
+ * Flow:
+ *   1. Browser hits `/@swarm/api/<rest>` from inside an iframe of `/p/:id`.
+ *   2. We parse the `page_session` cookie, verify HMAC + expiry.
+ *   3. Look up the page; map `agentId` → `X-Agent-ID`.
+ *   4. Re-issue the request to the same API server's `/api/<rest>` with
+ *      `Authorization: Bearer ${API_KEY}` and `X-Agent-ID: ${page.agentId}`
+ *      injected server-side. The bearer NEVER touches the browser.
+ *
+ * Cookie IS the auth — this route opts out of the global bearer gate via
+ * `route({ auth: { apiKey: false } })`. Unknown paths fail closed (the
+ * `isPublicRoute` check defaults to bearer-required), so we must declare the
+ * route here even though we don't use route().match() for the actual
+ * dispatch (we use a startsWith check below — segment-based matching gets
+ * unwieldy for an arbitrary suffix).
+ */
+
+// Registered purely so the global bearer-gate (`isPublicRoute`) skips the
+// API-key check for /@swarm/api/* requests. The handler below does its own
+// cookie validation. The path pattern uses a single dynamic segment as a
+// stand-in; the actual route accepts ANY suffix and is matched manually via
+// `req.url.startsWith("/@swarm/api/")` for clarity.
+route({
+  method: "get",
+  path: "/@swarm/api/{path}",
+  pattern: ["@swarm", "api", null],
+  exact: false,
+  summary: "Cookie-gated proxy to the swarm API (used by db-backed page iframes)",
+  tags: ["Pages"],
+  responses: {
+    200: { description: "Proxied response from the underlying /api/* endpoint" },
+    401: { description: "No or invalid page-session cookie" },
+    404: { description: "Page referenced by the cookie no longer exists" },
+  },
+  auth: { apiKey: false },
+});
+route({
+  method: "post",
+  path: "/@swarm/api/{path}",
+  pattern: ["@swarm", "api", null],
+  exact: false,
+  summary: "Cookie-gated proxy to the swarm API (POST)",
+  tags: ["Pages"],
+  responses: {
+    200: { description: "Proxied response" },
+    401: { description: "No or invalid page-session cookie" },
+  },
+  auth: { apiKey: false },
+});
+route({
+  method: "put",
+  path: "/@swarm/api/{path}",
+  pattern: ["@swarm", "api", null],
+  exact: false,
+  summary: "Cookie-gated proxy to the swarm API (PUT)",
+  tags: ["Pages"],
+  responses: {
+    200: { description: "Proxied response" },
+    401: { description: "No or invalid page-session cookie" },
+  },
+  auth: { apiKey: false },
+});
+route({
+  method: "delete",
+  path: "/@swarm/api/{path}",
+  pattern: ["@swarm", "api", null],
+  exact: false,
+  summary: "Cookie-gated proxy to the swarm API (DELETE)",
+  tags: ["Pages"],
+  responses: {
+    200: { description: "Proxied response" },
+    401: { description: "No or invalid page-session cookie" },
+  },
+  auth: { apiKey: false },
+});
+route({
+  method: "patch",
+  path: "/@swarm/api/{path}",
+  pattern: ["@swarm", "api", null],
+  exact: false,
+  summary: "Cookie-gated proxy to the swarm API (PATCH)",
+  tags: ["Pages"],
+  responses: {
+    200: { description: "Proxied response" },
+    401: { description: "No or invalid page-session cookie" },
+  },
+  auth: { apiKey: false },
+});
+
+const PROXY_PREFIX = "/@swarm/api/";
+
+/**
+ * Handle `/@swarm/api/*` requests. Returns `true` if the request was handled
+ * (response sent), `false` if not — caller continues to the next handler.
+ *
+ * Place BEFORE `handlePages` in the central `handlers` array — `/@swarm/api/*`
+ * does not overlap `/api/pages/*` segment-wise (different first segment), but
+ * we keep the ordering explicit.
+ */
+export async function handlePageProxy(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  const url = req.url ?? "";
+  if (!url.startsWith(PROXY_PREFIX)) return false;
+
+  // Strip query string for cookie/path checks, but preserve it for the
+  // forwarded URL so callers like `/me?include=inbox` still work.
+  const queryIdx = url.indexOf("?");
+  const pathPart = queryIdx === -1 ? url : url.slice(0, queryIdx);
+  const queryPart = queryIdx === -1 ? "" : url.slice(queryIdx);
+
+  // ─── Cookie validation ────────────────────────────────────────────────────
+  const payload = await extractAndVerifyCookie(req);
+  if (!payload) {
+    jsonError(res, "no page session", 401);
+    return true;
+  }
+
+  const page = getPage(payload.pageId);
+  if (!page) {
+    // Cookie was issued before the page was deleted. Treat as a stale session
+    // rather than 404 so the client knows to refresh / re-launch.
+    jsonError(res, "page session no longer valid", 401);
+    return true;
+  }
+
+  // ─── Rewrite + forward ─────────────────────────────────────────────────────
+  // `/@swarm/api/me` → `/api/me`. Preserve query string.
+  //
+  // This is an IN-PROCESS proxy — we always dispatch to the same server we're
+  // running in. We deliberately do NOT use `deriveApiBaseUrl(req)`: that would
+  // honour `MCP_BASE_URL` (which may be an ngrok tunnel or other external host
+  // pointing back at us), forcing a network round-trip through the public
+  // surface and breaking when `localhost:<PORT>` is reachable but the public
+  // URL isn't (test envs, offline dev, restrictive networks).
+  const rewrittenPath = pathPart.replace(PROXY_PREFIX, "/api/");
+  const port = process.env.PORT || "3013";
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const targetUrl = `${baseUrl}${rewrittenPath}${queryPart}`;
+
+  const apiKey = process.env.API_KEY ?? "";
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${apiKey}`,
+    "X-Agent-ID": page.agentId,
+  };
+
+  // Forward content-type / accept verbatim for non-GET so JSON bodies work.
+  const reqContentType = req.headers["content-type"];
+  if (reqContentType) {
+    headers["Content-Type"] = Array.isArray(reqContentType) ? reqContentType[0]! : reqContentType;
+  }
+  const reqAccept = req.headers.accept;
+  if (reqAccept) {
+    headers.Accept = Array.isArray(reqAccept) ? reqAccept[0]! : reqAccept;
+  }
+
+  // Pull the body if there is one. We DO buffer here — page traffic is
+  // expected to be small JSON payloads, and streaming would complicate cookie
+  // failure-mode handling.
+  const method = (req.method ?? "GET").toUpperCase();
+  let body: Buffer | undefined;
+  if (method !== "GET" && method !== "HEAD") {
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) chunks.push(chunk as Buffer);
+    if (chunks.length > 0) body = Buffer.concat(chunks);
+  }
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(targetUrl, {
+      method,
+      headers,
+      body,
+      // Prevent the runtime from following redirects — surface them to the
+      // caller as-is so the SDK sees the same response it would direct-fetching.
+      redirect: "manual",
+    });
+  } catch (err) {
+    // Don't echo the underlying error to the client (could leak target URL
+    // shape under some env-var typos). Log to server, send generic 502.
+    console.error("[page-proxy] upstream fetch failed:", err);
+    jsonError(res, "upstream error", 502);
+    return true;
+  }
+
+  // Pipe upstream response back. Preserve status + content-type.
+  const upstreamCt = upstream.headers.get("content-type");
+  if (upstreamCt) res.setHeader("Content-Type", upstreamCt);
+
+  // Copy a small allowlist of useful headers. Don't blanket-forward — upstream
+  // may include `Set-Cookie` we don't want to re-emit, etc.
+  const cacheControl = upstream.headers.get("cache-control");
+  if (cacheControl) res.setHeader("Cache-Control", cacheControl);
+
+  res.writeHead(upstream.status);
+  const buf = Buffer.from(await upstream.arrayBuffer());
+  res.end(buf);
+  return true;
+}